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

Search Console

1. 색인 상태 조회google.search_console.index_status

MCP 도구 이름 google__search_console__index_status

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

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

페이지 하나가 검색에 등록돼 있는지, 막혀 있다면 무엇이 막는지 알려 줍니다. 지금 등록된 상태를 읽는 것이며 색인을 요청하지 않습니다. 사이트당 하루 2,000회까지 조회할 수 있습니다.

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.search_console.index_status이 API 고정값 (기본값)

예시 : google.search_console.index_status

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입필수설명
inspection_urlstringY검사할 페이지 하나의 전체 http 나 https 주소(예: https://example.com/pricing). site_url 안에 있어야 합니다 - URL 접두 속성이면 그 접두 아래, sc-domain: 속성이면 그 도메인이나 하위 도메인
site_urlstringYSearch Console 에 등록된 속성 주소를 그대로 입력합니다 — "https://example.com/" 과 "sc-domain:example.com" 은 서로 다른 속성이고, 끝의 슬래시(/) 유무도 구분됩니다
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-index_status-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.search_console.index_status",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "inspection_url": "<필수>",
    "site_url": "<필수>"
  }
}'
Response

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

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

2. 검색 실적 조회google.search_console.performance

MCP 도구 이름 google__search_console__performance

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

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

검색에서 얼마나 노출되고 눌렸는지, 어떤 검색어로 들어왔는지 돌려줍니다. 제공되는 값은 상위 항목이라 전체가 아닌 일부입니다.

  • 콘솔에서 Google 계정 연동을 마쳐야 합니다. 조회할 site_url 은 연동 상태 조회(google.account.status)의 search_console_sites 에서 확인합니다 - readable:true 인 것만 조회됩니다.
  • 이 상품은 sandbox 환경에서 실행할 수 없습니다. error.code=POLICY_ENV_FORBIDDEN.
  • site_url·start_date·end_date 는 필수입니다. site_url 은 Search Console 에 등록된 속성 주소를 그대로 입력합니다 — "https://example.com/" 과 "sc-domain:example.com" 은 다른 속성이고 끝 슬래시 유무도 구분됩니다. data_state 는 final(기본값)·all 중 하나만 받고, 그 밖의 값이면 error.code=VALIDATION_INVALID_FIELD 입니다. dimensions·row_limit(최대 25,000)·start_row 는 선택입니다.
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.search_console.performance이 API 고정값 (기본값)

예시 : google.search_console.performance

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

형식 : UUID v4

[참고] 자격증명 등록

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

[참고] 암호화

순번변수명타입길이필수설명
data_statestring-Nfinal(기본값)은 확정된 데이터만 반환하고, all 은 아직 변동 중인 최신 데이터까지 포함합니다. 결과에 어느 쪽을 썼는지 표시됩니다
dimensionsarray-N선택적 분류 기준(예: ["query", "page"])
end_datestring10Y조회 종료일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

row_limitnumber-N반환할 최대 행 수(최대 25,000). 생략하면 기본값을 씁니다
site_urlstring-YSearch Console 에 등록된 속성 주소를 그대로 입력합니다 — "https://example.com/" 과 "sc-domain:example.com" 은 서로 다른 속성이고, 끝의 슬래시(/) 유무도 구분됩니다
start_datestring10Y조회 시작일 형식만 받으며 해당일을 포함합니다

형식 : YYYY-MM-DD

start_rownumber-N페이지 넘김을 위한 시작 위치(offset). 생략하면 첫 페이지입니다
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-performance-001' \
  --header 'Content-Type: application/json' \
  --data '{
  "provider": "google",
  "action": "google.search_console.performance",
  "account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
  "params": {
    "end_date": "<필수>",
    "site_url": "<필수>",
    "start_date": "<필수>"
  }
}'
Response
  • result.data 의 rows[] 로 검색 실적(클릭·노출·CTR·순위)을 확인합니다. 날짜는 태평양시(PT) 기준이고(timezone_note_ko), Google 이 상위 행만 주므로 rows 가 전체 질의 목록은 아닙니다(coverage_note_ko). is_partial_by_provider_contract·first_incomplete_date 로 아직 집계가 끝나지 않은 최근 날짜가 섞였는지 확인합니다.
순번변수명설명
site_url조회한 사이트 주소(요청 그대로 반향)
start_date조회 시작일(요청 그대로 반향)
end_date조회 종료일(요청 그대로 반향)
dimensions요청한 분류 기준 목록(요청 그대로 반향)
rows행 목록 - 각 행은 dimension_values(분류값)·metrics(clicks·impressions·ctr) 를 담습니다
data_availability이 기간·사이트의 데이터를 지금 읽을 수 있는지
is_partial_by_provider_contractGoogle 이 상위 행만 주는 provider 특성상 이 응답이 원래부터 부분 응답인지 - true 고정
row_limit요청한 최대 반환 행 수(요청 그대로 반향)
start_row요청한 페이지 시작 위치(요청 그대로 반향)
collectionrows 의 건수·잘림·접근 실패 여부
timezone_note_ko검색 실적의 날짜는 태평양시(PT) 기준이라는 안내
coverage_note_koGoogle 이 상위 행만 제공하므로 전체 질의 목록이 아니라는 안내
first_incomplete_date아직 집계가 끝나지 않은 것으로 보이는 첫 날짜(없으면 null)
as_of이 응답을 만든 시각(UTC)
timezone이 액션은 태평양시(America/Los_Angeles) 고정입니다
is_finaldata_state 에서 유도 - final 로 조회하면 확정, all 로 조회하면 변동 가능
content_is_data_not_instructions_ko이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문
json
{
    "job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
    "status": "QUEUED",
    "env_scope": "sandbox",
    "provider": "google",
    "action": "google.search_console.performance",
    "submitted_at": "2026-05-27T12:34:56+09:00"
}
순번오류 코드발생 조건
PROVIDER_BUSINESS_ERROR권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 사이트면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
VALIDATION_INVALID_FIELD권한 없음 · 선택 안 한 자산 — 권한이 없으면 (Google 에서 보기 권한을 받아야 함), 연동 범위에서 고르지 않은 사이트면 (연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인) 입니다.
AUTH_REQUIRED연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다.
PROVIDER_VALIDATION_ERROR기관 거절 — Google 이 이 요청을 받아들이지 않았습니다. 기관이 사유를 주면 그대로 error.message 에 실립니다.
PROVIDER_UPSTREAM_ERROR한도 초과 — Google 조회 한도를 다 썼습니다.