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

youtube

1. 채널 성과 조회 (YouTube 연동)google.youtube.analytics.report

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

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

YouTube 채널 하나의 기간별 애널리틱스 보고서를 조회합니다: 조회수, 시청 시간, 구독자 등 요청한 채널 지표입니다. 조회 전용이며 기간은 양끝 포함입니다. YouTube 가 처리를 마친 날짜만 응답에 포함되므로 최근 며칠은 빠지거나 나중에 바뀔 수 있고, 결과의 is_final 이 provisional 로 표시됩니다. 수익 지표는 여기서 제공되지 않습니다. 모든 지표는 channel_metrics 아래로만 돌아옵니다 - 공통 지표 축과 같은 뜻이 아니기 때문입니다. start_index 는 0 이 아니라 1부터 셉니다.

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.youtube.analytics.report이 API 고정값 (기본값)

예시 : google.youtube.analytics.report

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
channel_idstring-YYouTube 채널 ID(채널의 고급 계정 설정에 표시되는 값, 현재는 "UC" 로 시작합니다). 이 연동에서 고객이 선택한 채널이어야 합니다
dimensionsarray-N선택적 분류 기준(예: ["day"] 나 ["country"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

filtersstring-N선택적 YouTube 애널리틱스 필터 표현식(예: "country==KR"). 여러 개는 세미콜론으로 잇습니다
max_resultsnumber-N반환할 최대 행 수. 생략하면 기본값을 씁니다
metricsarray-Y조회할 YouTube 애널리틱스 지표 이름 목록(예: ["views", "estimatedMinutesWatched"]). channel_metrics 아래로 반환됩니다
sortstring-N정렬 기준 필드 이름을 쉼표로 나열합니다(선택). 앞에 -를 붙이면 내림차순입니다(예: "-views")
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

start_indexnumber-N페이지 넘김을 위한 시작 행 번호. 1부터 셉니다 - 첫 행이 0 이 아니라 1입니다. 생략하면 첫 페이지입니다
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.youtube.analytics.report",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "channel_id": "<필수>",
    "end_date": "<필수>",
    "metrics": "<필수: array>",
    "start_date": "<필수>"
  }
}'
Response

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

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

2. 예약 보고 만들기 (YouTube 연동)google.youtube.report_job.create

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

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

연결한 YouTube 계정에 대량 보고 예약을 만들어 기관이 그 보고를 날마다 만들게 합니다. 같은 종류의 예약이 이미 있으면 새로 만들지 않고 그것을 그대로 쓰며, 그 사실을 reused 칸으로 알려 줍니다. 만드는 것은 예약뿐입니다 - 고객 콘텐츠를 바꾸지 않고, 무엇도 게시하지 않으며, 보고 파일 본문도 돌려주지 않습니다. 만든 뒤에는 예약 보고 목록 조회로 어떤 보고가 나왔는지 확인합니다. 첫 보고는 바로 나오지 않습니다.

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.youtube.report_job.create이 API 고정값 (기본값)

예시 : google.youtube.report_job.create

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
namestringN선택적 예약 이름(100자 이하). 생략하면 보고 종류(report_type_id) 값을 이름으로 씁니다
report_type_idstringY예약할 보고 종류. 예: channel_basic_a3 또는 channel_combined_a3
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-create-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.youtube.report_job.create",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "report_type_id": "<필수>"
  }
}'
Response

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

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

3. 예약 보고 목록 조회 (YouTube 연동)google.youtube.report_job.read

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

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

연결한 YouTube 계정에 예약된 대량 보고 작업과 각 작업이 낸 보고를 조회합니다(덮는 기간, 만들어진 시각, 받을 수 있는 파일이 있는지). 조회 전용이며 작업을 만들거나 지우지 않습니다. job_id 를 주지 않으면 어떤 작업이 있는지, 주면 그 작업이 낸 보고가 무엇인지 답합니다. 보고 파일 본문은 돌려주지 않습니다. 시각은 기관이 적은 그대로 RFC 3339 UTC 입니다.

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.youtube.report_job.read이 API 고정값 (기본값)

예시 : google.youtube.report_job.read

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
created_afterstringN선택적 RFC 3339 시각. 그 시각 이후에 만들어진 보고만 돌려줍니다
job_idstringN보고 작업 id. 생략하면 어떤 작업이 있는지 먼저 목록으로 답하고, 그 목록에서 id 를 얻습니다
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-read-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.youtube.report_job.read",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {}
}'
Response

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

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