수집 방식과 권한의 판단
순위 측정을 자동화할 때에는 먼저 데이터를 얻는 방식과 명시적 권한을 검토합니다. Google은 순위 조사 목적의 검색 결과 스크래핑과 명시적 권한 없이 이뤄지는 다른 자동 검색 접근을 머신 생성 트래픽에 포함합니다. 자동으로 숫자를 얻을 수 있다는 편의성만으로 허용된 수집이라고 판단하지 않고, 실제 출처와 그 방식에 적용되는 권한 근거를 읽습니다.
공식 스팸 정책은 자동 검색어를 Google에 보내는 관행이 리소스를 소비하고 사용자에게 최선의 서비스를 제공하는 데 방해가 된다고 설명합니다. 문서에는 이러한 활동이 Google의 스팸 정책과 서비스 약관을 위반한다는 조건이 명시돼 있습니다. 차단을 우회해 더 많은 결과를 얻는 구현을 선택하는 대신, 어떤 방식으로 접근하는 도구인지 먼저 조사합니다. 출처를 알 수 없는 순번을 병원의 확정 실적으로 쓰지 않습니다.
공식 Search Analytics query 문서는 Search Console에 정의된 속성의 검색 트래픽 데이터를 얻는 경로를 설명합니다. 이 요청에는 읽기 전용 또는 웹마스터 권한 범위 중 하나를 사용한 인증이 필요합니다. 해당 속성의 데이터를 읽을 수 있는 인증 범위와 공개 검색 결과를 자동으로 스크래핑할 권한은 서로 대체되는 근거가 아닙니다. API 문서가 있다는 사실을 모든 자동 검색 접근의 허가로 확대하지 않습니다.
| 응답에 함께 제공되는 측정값 | 공식 정의 | 평균 순위와 구별할 항목 |
|---|---|---|
| clicks | 결과 행의 클릭 수 | 순번이 아닌 결과 선택의 횟수 |
| impressions | 결과 행의 노출 수 | 순번이 아닌 결과 표시의 횟수 |
| ctr | 행의 클릭률(0~1.0 포함) | 위치 값과 다른 선택 비율 |
반환되는 position은 검색 결과의 평균 게재순위입니다. 자료에 숫자가 있다고 해서 특정 장소의 사용자가 지금 보는 개별 순번을 뜻하는 것은 아닙니다. 같은 행에 표시된 측정기준과 조회 기간을 읽어 어떤 결과들의 평균인지 설명합니다. 도구가 평균을 가져오는 방식이라면 매 순간의 고정 순위처럼 보고하지 않습니다.
공식 경로에서도 반환 정보에는 한계가 있습니다. Search Analytics query는 Search Console 내부 제한의 영향을 받으며 모든 데이터 행을 보장하지 않는다고 문서가 설명합니다. 자료의 출처가 공식이라는 사실과 모든 검색어가 빠짐없이 제공됐다는 주장은 별개입니다. 보고서에서 볼 수 있는 범위로 설명하고, 반환되지 않은 행의 실제 값을 만들어 빈칸을 채우지 않습니다.
요청 범위와 반환 자료의 의미
요청의 기간에는 최소 하루 이상이 필요하며 시작일과 종료일은 각각 범위에 포함됩니다. 시작일은 종료일보다 빠르거나 같아야 한다는 조건도 명시됩니다. 자동 수집 결과를 비교할 때 기간의 양 끝이 포함됐는지 읽어 같은 날짜 범위를 가리키는 자료인지 대조합니다. 요청이 어느 날부터 어느 날까지였는지 알지 못하면 기간 전체의 평균을 같은 시점의 관측이라고 표현하지 않습니다.
기간은 태평양 시간 기준이며 공식 문서에는 UTC와의 차이가 -7시간 또는 -8시간으로 안내됩니다. 표에 적은 날짜가 관측자의 현지 하루와 같은 범위인지 먼저 구별합니다. 날짜 이름이 일치하더라도 실제 포함되는 시간이 다르면 결과를 같은 하루의 수집으로 묶지 않습니다. 이 기준을 임의로 현지 시간으로 바꿔 설명하지 않고 원자료의 시간대를 함께 읽습니다.
| 요청 유형 | 공식 데이터 범위 | 혼동하지 않을 결과 |
|---|---|---|
| web 기본값 | Google 검색의 전체 탭 | 디스커버·Google 뉴스까지 모두 포함한 값 |
| news | Google 검색의 뉴스 탭 | 뉴스 앱과 news.google.com의 결과 |
| googleNews | news.google.com과 Google 뉴스 앱 | 검색의 뉴스 탭 결과 |
| image·video | 각각 이미지·동영상 검색 | 다른 유형의 검색 데이터 |
측정기준을 지정하지 않으면 모든 값이 하나의 행으로 결합됩니다. 측정기준을 지정했을 때에는 제공한 순서대로 그룹화되며 같은 값의 조합이 행의 고유 키가 됩니다. 행이 하나라는 관측만으로 검색어가 하나뿐이었다고 설명하지 않습니다. 어떤 그룹으로 읽어야 하는지가 요청에 정해졌는지 조사하면 결과 행의 의미를 구별할 수 있습니다.
페이지별로 필터링하거나 그룹화했을 때에는 속성별 집계를 할 수 없다는 공식 제한이 있습니다. 페이지별 집계에서는 표준 URI 기준으로 값을 묶는다는 조건도 제시됩니다. 반환된 주소가 실제 접속 문자열과 항상 같은 것으로 추정하지 않고 페이지 집계의 기준을 읽습니다. 어느 URL의 평균 순위를 설명하는 자료인지 분명히 해야 다른 주소의 값을 한 페이지에 덧붙이지 않습니다.
집계 유형을 자동 이외의 값으로 지정했다면 유효한 요청의 결과는 지정 유형과 일치합니다. 유효하지 않은 유형을 요구하면 오류가 나고 API가 그 유형을 임의로 변경하지 않는다고 문서는 설명합니다. 자동 도구에서 결과가 생성되지 않았다면 요청 조건의 오류인지 조사할 수 있습니다. 응답이 없다는 상태를 사이트의 검색 노출이 전부 사라졌다는 자료로 바꾸지 않습니다.
반환할 최대 행 수의 유효 범위는 1에서 25,000이며 기본값은 1,000입니다. 이 수치는 데이터 표의 반환 한도이고 검색 결과의 순위 범위가 아닙니다. 도구가 기본 요청으로 받은 행의 수를 전체 검색어 개수나 상위 몇 위의 결과라고 이름 붙이지 않습니다. 필요한 분석 질문에 맞는 행이 실제 제공됐는지 수집 범위와 함께 읽습니다.
디스커버 또는 Google 뉴스 유형의 자료에서는 속성별 집계가 지원되지 않는다는 조건도 명시돼 있습니다. 웹 검색에서 사용한 집계 선택을 다른 데이터 유형에 그대로 적용할 수 있다고 추정하지 않습니다. 뉴스 쇼케이스 패널별 집계는 별도의 검색 노출 필터와 지정 유형에 맞아야 하므로, 패널 기준의 값을 일반 페이지별 순위와 같은 단위로 읽지 않습니다. 수집 도구가 어느 유형과 집계 조합을 사용했는지 알아야 반환된 값의 대상을 설명할 수 있습니다.
최근 데이터의 처리 상태
최근 자료를 받아 쓰는 경우에는 완료된 데이터와 처리 중인 데이터를 구별해야 합니다. dataState가 생략되거나 final이면 완료된 데이터만 반환되고 all이면 최신 데이터도 포함된다는 것이 공식 설명입니다. 최근 값이 계속 수집될 가능성이 있는 상태를 읽지 않고 과거 확정값과 같은 확정도로 비교하지 않습니다. 자동 수집 시각만 기록하는 것보다 어떤 처리 상태를 선택했는지 읽는 일이 필요합니다.
시간별 데이터를 포함하는 hourly_all은 시간별 측정기준으로 그룹화할 때 사용하도록 안내돼 있습니다. 날짜별 묶음과 시간별 묶음은 같은 행 구조라고 가정하지 않습니다. 자료에서 어느 시간 단위를 읽었는지와 요청한 데이터 상태를 대응시켜야 부분적으로 수집된 시간을 완료된 하루의 결과처럼 설명하는 일을 피할 수 있습니다.
응답에 포함될 수 있는 metadata는 처리 상태의 맥락을 제공합니다. 최근 데이터를 요청했다면 일부 행이 아직 수집·처리 중인 불완전한 자료일 수 있다는 안내가 있습니다. 해당 객체에 제공된 날짜와 시간은 America/Los_Angeles 시간대이므로 원래 기준으로 읽습니다. 이 정보가 있는 자료에서 값이 나중에 달라졌다면 사이트 순위가 갑자기 변한 것인지 처리 중 자료였는지 먼저 구별합니다.
불완전한 첫 날짜나 첫 시간 필드는 특정 조건에서만 제공됩니다. 날짜별 그룹화와 all 상태, 또는 시간별 그룹화와 hourly_all 상태에 맞고 요청 기간에 불완전한 자료가 포함돼야 해당 필드가 채워집니다. 공식 문서는 그 시점 이후 값이 여전히 크게 달라질 수 있다고 설명합니다. 필드가 없는 응답을 읽을 때에는 그 조건에서 제공되도록 요청됐는지도 조사하며 모든 처리 상태가 자동으로 증명됐다고 표시하지 않습니다.
필터로 자료를 좁히는 동작과 표시할 그룹을 정하는 동작은 구별됩니다. 공식 문서에 따르면 어떤 측정기준으로 그룹화하지 않았어도 그 측정기준으로 필터링할 수 있습니다. 국가·기기·페이지·검색어 등의 조건이 적용된 자료를 모든 방문자의 자료로 일반화하지 않습니다. 요청 조건에서 무엇을 포함하거나 제외했는지 읽어 자동 도구가 반환한 평균의 대상 범위를 설명합니다.
자주 묻는 질문
행이 0개인 성공 응답은 항상 노출이 없다는 뜻인가요?
startRow가 쿼리의 결과 수를 넘으면 행이 0개인 성공 응답을 반환할 수 있습니다. 오류 없는 응답과 사이트 노출이 없다는 판정은 같지 않으므로 조회를 시작한 행의 위치를 읽습니다.
날짜별 행에 특정 날짜가 없으면 0으로 채워도 되나요?
날짜를 측정기준으로 사용하면 데이터가 없는 날짜는 목록에서 생략됩니다. 생략된 상태를 제공된 측정값으로 바꾸지 않고, 실제 어떤 날짜에 자료가 반환됐는지 구별합니다.
결과의 첫 행이 언제나 가장 높은 순위인가요?
일반 결과는 클릭수 내림차순이고 동률의 순서는 임의입니다. 날짜별 그룹화에서는 오래된 날짜부터 오름차순으로 정렬됩니다. 반환 순서를 게재순위 순서와 혼동하지 않습니다.
검색어 필터는 언제나 대소문자를 무시하나요?
페이지·검색어의 equals와 notEquals는 대소문자를 구분하지만 contains와 notContains는 구분하지 않는다고 문서가 밝힙니다. 선택한 연산자의 조건을 읽어 서로 다른 필터 결과를 같은 수집이라고 표현하지 않습니다.
필터 그룹에서 조건 하나만 맞으면 되는 방식도 제공되나요?
지정 문서의 groupType은 and를 지원하며 하나 이상만 일치하는 방식은 아직 지원되지 않는다고 표시됩니다. 도구 설명을 읽을 때 공식 지원 범위를 넘는 필터 조합이 자동으로 적용됐다고 추정하지 않습니다.