개발자 문서
서비스 소개키 관리자격증명 등록OpenAPI콘솔
API 레퍼런스

ads

POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 네 캠페인 유형(검색, 디스플레이, 최대실적, 디맨드젠) 성과를 한 번에 조회합니다. 동영상 캠페인은 포함되지 않으며 동영상 광고 성과 조회를 씁니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.channels.report이 API 고정값 (기본값)

예시 : google.ads.channels.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.channels.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.channels.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 Demand Gen 캠페인 기간별 성과를 조회합니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.demand_gen.report이 API 고정값 (기본값)

예시 : google.ads.demand_gen.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.demand_gen.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.demand_gen.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 디스플레이(Display) 캠페인 기간별 성과를 조회합니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.display.report이 API 고정값 (기본값)

예시 : google.ads.display.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.display.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.display.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 Performance Max 캠페인 기간별 성과를 조회합니다. Performance Max 는 광고그룹(ad group) 관련 필드를 보고하지 않으므로, 그런 필드를 요청하면 활동 없음으로 오해될 빈 결과 대신 명확한 사유와 함께 거부됩니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.pmax.report이 API 고정값 (기본값)

예시 : google.ads.pmax.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.pmax.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.pmax.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 검색(Search) 캠페인 기간별 성과를 조회합니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.search.report이 API 고정값 (기본값)

예시 : google.ads.search.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.search.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.search.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
POSThttps://api.xdata.kr/v1/jobsX-Env-Scope: sandbox

샌드박스입니다. 실제 기관을 호출하지 않는 모의 응답이며 일일 한도가 없습니다.

Google Ads 계정 하나의 동영상(Video) 캠페인 기간별 성과를 조회합니다. 동영상 전용 지표 이름은 metrics.video_trueview_views 와 metrics.video_trueview_view_rate 이며, metrics.video_views 는 없습니다. 조회 전용이며 기간은 양끝 포함이고 광고 계정 자체의 시간대를 따릅니다(결과에 함께 옵니다). 응답에서 metrics.impressions, metrics.clicks, metrics.ctr 세 지표는 요청한 이름 그대로 공통 지표 칸에 실리고, 그 외 지표는 전부 channel_metrics 아래 요청한 이름으로 돌아옵니다. metrics.conversions 는 channel_metrics 에 남습니다 - Google Ads 와 GA4 가 세는 방식이 다르기 때문입니다. metrics.cost_micros 를 요청하면 각 행에 metrics.cost 도 함께 옵니다 - 같은 금액을 계정 통화의 최소단위 정수로(반올림) 바꾼 값입니다. 최상위의 currency_code 와 currency_minor_unit_digits 가 소수점 위치를 알려줍니다(원화는 0, 달러는 2). 통화를 모르면 metrics.cost 는 없고 원값인 metrics.cost_micros 만 돌아옵니다. row_limit 은 이 호출이 돌려주는 행 수일 뿐 Google 에 보내는 제한이 아닙니다 - Google 의 페이지 크기가 고정이기 때문입니다. 더 가져올 행이 있으면 결과에 truncated 와 data_availability: partial_collection 이 표시됩니다. next_page_token 은 이어받기가 안전할 때만 채워지며, 없으면 기간을 좁히거나 row_limit 을 올려야 합니다.

Request
순번변수명필수설명
AuthorizationYAPI 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다.

형식 : Basic base64("{client_id}:{client_secret}")

[참고] 인증

X-Env-ScopeY호출 환경입니다.
  • sandbox샌드박스 — 모의 응답
  • real_test데모 — 하루 100 사용 토큰
  • production정식 — 유료 플랜 전용

[참고] 환경

Idempotency-KeyY재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다.

[참고] 재시도

Content-TypeY요청 본문 형식입니다.
  • application/json고정값 (기본값)
X-Trace-IdN추적 아이디입니다. 지정하지 않으면 서버가 발급합니다.
순번변수명타입길이필수설명
providerstring-Y호출할 기관입니다.
  • google이 API 고정값 (기본값)

예시 : google

actionstring-Y호출할 작업입니다.
  • google.ads.video.report이 API 고정값 (기본값)

예시 : google.ads.video.report

account_link_idstring36조건부등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명 중 대표로 지정한 것이 쓰입니다. 대표가 없으면 등록한 자격증명이 하나뿐일 때만 자동으로 선택되고, 둘 이상이면 직접 지정해야 합니다.

형식 : UUID v4

[참고] 자격증명 등록

paramsobject-Y작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다.
encrypted_fieldsobject-N민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다.

[참고] 암호화

순번변수명타입길이필수설명
customer_idstring-YGoogle Ads 계정 번호(하이픈 있거나 없거나 - "123-456-7890" 과 "1234567890" 은 같은 계정입니다). 이 연동에서 고객이 선택한 계정이어야 합니다
dimensionsstring-N선택적 분류 기준 필드 이름(예: ["segments.date", "campaign.name"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

metricsstring-Y조회할 Google Ads 지표 필드 이름 목록(예: ["metrics.impressions", "metrics.clicks", "metrics.cost_micros"]). 전체 필드 경로를 씁니다
page_tokenstring-N이전 호출의 next_page_token 값. 생략하면 첫 페이지입니다
row_limitstring-N반환할 최대 행 수. 생략하면 기본값을 씁니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

bash
curl --request POST \
  --url 'https://api.xdata.kr/v1/jobs' \
  --header 'Authorization: Basic {base64(client_id:client_secret)}' \
  --header 'X-Env-Scope: sandbox' \
  --header 'Idempotency-Key: demo-report-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.ads.video.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "customer_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수>",
    "start_date": "<필수>"
  }
}'
Response

이 API 는 기관 응답 본문을 그대로 전달합니다. 고정 필드 목록이 없습니다.

json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.ads.video.report",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}