Search Analytics: query

승인 필요

직접 정의한 필터와 매개변수를 사용하여 검색 트래픽 데이터를 쿼리합니다. 이 메서드는 정의된 row key (측정기준)로 그룹화된 0개 이상의 행을 반환합니다. 날짜 범위를 1일 이상 정의해야 합니다.

날짜가 측정기준 중 하나인 경우 데이터가 없는 날은 결과 목록에서 생략됩니다. 데이터가 있는 날짜를 알아보려면 원하는 기간에 대해 날짜별로 그룹화된 필터를 사용하지 않고 쿼리를 실행합니다.

결과는 클릭수를 내림차순으로 정렬합니다. 두 행의 클릭수가 같으면 임의의 방식으로 정렬됩니다.

이 메서드를 호출하는 방법은 python 샘플을 참조하세요.

이 API는 Search Console의 내부 제한으로 제한되며, 모든 데이터 행이 아닌 상위 행이 반환될 것을 보장하지 않습니다.

사용 가능한 데이터 양의 한도 보기

JSON POST 예시: 
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
지금 사용해 보기

요청

HTTP 요청

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

매개변수

매개변수 이름 값 설명
경로 매개변수
siteUrl string Search Console에 정의된 속성의 URL입니다. 예: http://www.example.com/ (URL 접두사 속성) 또는 sc-domain:example.com (도메인 속성)

승인

이 요청에는 다음 범위 중 최소 하나를 사용하여 인증이 필요합니다. (인증 및 승인에 대해 자세히 알아보기)

범위
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

요청 본문

요청 본문에 다음과 같은 구조의 데이터를 제공합니다.

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
속성 이름 값 설명 Notes
startDate string [필수사항] PT 시간 (UTC - 7:00/8:00)으로 표시된 YYYY-MM-DD 형식의 요청 기간의 시작일입니다. 종료일 이전이어야 합니다. 이 값은 범위에 포함됩니다.
endDate string [필수] PT 시간 (UTC - 7:00/8:00)으로 표기된 YYYY-MM-DD 형식의 요청된 기간의 종료일입니다. 시작일보다 크거나 같아야 합니다. 이 값은 범위에 포함됩니다.
dimensions[] list [선택사항] 결과를 그룹화할 기준이 될 0개 이상의 측정기준입니다.결과는 이러한 측정기준을 입력한 순서대로 그룹화됩니다.dimensionFilterGroups[].filters[].dimension 및 'date'에 모든 측정기준 이름을 사용할 수 있습니다.그룹화 측정기준 값이 결합되어 각 결과 행에 대한 고유 키가 생성됩니다. 측정기준을 지정하지 않으면 모든 값이 하나의 행으로 결합됩니다. 그룹화할 수 있는 측정기준의 수에는 제한이 없지만 동일한 측정기준으로 두 번 그룹화할 수는 없습니다. 예: [국가, 기기]
searchType string 지원 중단되었습니다. 대신 type를 사용하세요.
type string [선택사항] 다음 유형으로 결과를 필터링합니다.
  • "discover": 디스커버 결과
  • 'googleNews': Android 및 iOS용 news.google.com 및 Google 뉴스 앱의 검색결과 Google 검색의 '뉴스' 탭의 결과는 포함되지 않습니다.
  • 'news': Google 검색의 '뉴스' 탭의 검색결과입니다.
  • 'image': Google 검색의 '이미지' 탭의 검색결과입니다.
  • "video": 동영상 검색결과
  • 'web': [기본값] Google 검색의 통합 ('전체') 탭으로 결과를 필터링합니다. 디스커버 또는 Google 뉴스 검색 결과는 포함되지 않습니다.
dimensionFilterGroups[] list [선택사항] 측정기준 그룹화 값에 적용할 0개 이상의 필터 그룹입니다. 응답에서 행이 반환되려면 모든 필터 그룹이 일치해야 합니다. 단일 필터 그룹 내에서 모든 필터가 일치해야 하는지 또는 하나 이상의 필터가 일치해야 하는지 지정할 수 있습니다.
dimensionFilterGroups[].groupType string 이 그룹의 모든 필터가 true ('and')를 반환해야 하는지, 하나 이상의 필터가 true를 반환해야 하는지 여부 (아직 지원되지 않음)입니다.

사용 가능한 값은 다음과 같습니다.
  • 'and': 필터 그룹이 true가 되려면 그룹의 모든 필터가 true를 반환해야 합니다.
dimensionFilterGroups[].filters[] list [선택사항] 행에 대해 테스트할 필터가 0개 이상입니다. 각 필터는 측정기준 이름, 연산자, 값으로 구성됩니다. 최대 길이는 4,096자(영문 기준)입니다. 예: 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string 이 필터가 적용되는 측정기준입니다. 여기에 나열된 측정기준으로 그룹화하지 않더라도 해당 측정기준으로 필터링할 수 있습니다.

사용 가능한 값은 다음과 같습니다.
  • 'country': 3자리 국가 코드 (ISO 3166-1 alpha-3)로 지정된 국가를 기준으로 필터링합니다.
  • 'device': 지정된 기기 유형을 기준으로 결과를 필터링합니다. 지원되는 값:
    • 데스크톱
    • 모바일
    • 태블릿
  • 'page': 지정된 URI 문자열을 기준으로 필터링합니다.
  • 'query': 지정된 쿼리 문자열을 기준으로 필터링합니다.
  • 'searchAppearance': 특정 검색결과 기능을 기준으로 필터링합니다. 사용 가능한 값의 목록을 보려면 'searchAppearance'로 그룹화된 쿼리를 실행하세요.
dimensionFilterGroups[].filters[].operator string [선택사항] 지정된 값이 행의 측정기준 값과 일치해야 하는 방식 (일치하지 않는 방식)입니다.

사용 가능한 값은 다음과 같습니다.
  • 'contains': 행 값이 표현식을 포함하거나 표현식과 같아야 합니다 (대소문자를 구분하지 않음).
  • "equals": [기본값] 표현식이 행 값과 정확하게 같아야 합니다 (페이지 및 쿼리 측정기준에서 대소문자를 구분).
  • 'notContains': 행 값에 표현식이 하위 문자열 또는 (대소문자를 구분하지 않음) 전체 일치로 포함되면 안 됩니다.
  • 'notEquals': 표현식이 행 값과 정확하게 같아서는 안 됩니다 (페이지 및 쿼리 측정기준에서 대소문자를 구분).
  • 'includingRegex': 일치해야 하는 RE2 구문 정규 표현식입니다.
  • 'excludingRegex': 일치시키면 안 되는 RE2 구문 정규 표현식입니다.
dimensionFilterGroups[].filters[].expression string 연산자에 따라 일치시키거나 제외할 필터의 값입니다.
aggregationType string

[선택사항] 데이터 집계 방법입니다. 속성별로 집계하는 경우 동일한 속성의 모든 데이터가 집계됩니다. 페이지 단위로 집계하는 경우 모든 데이터가 표준 URI로 집계됩니다. 필터링 또는 페이지를 기준으로 그룹화하려면 자동을 선택하세요. 그렇지 않으면 원하는 데이터 계산 방법에 따라 속성 또는 페이지별로 집계할 수 있습니다. 사이트와 페이지별로 데이터가 다르게 계산되는 방식을 알아보려면 도움말 문서를 참조하세요.

참고: 페이지별로 그룹화하거나 필터링하면 속성별로 집계할 수 없습니다.

auto 이외의 값을 지정하면 결과의 집계 유형이 요청된 유형과 일치하거나 잘못된 유형을 요청하는 경우 오류가 발생합니다. 요청된 유형이 유효하지 않은 경우 API는 집계 유형을 변경하지 않습니다.

사용 가능한 값은 다음과 같습니다.
  • "auto": [기본값] 서비스에서 적절한 집계 유형을 결정하도록 합니다.
  • 'byNewsShowcasePanel': 뉴스 쇼케이스 패널을 기준으로 값을 집계합니다. NEWS_SHOWCASE searchAppearance 필터 및 type=discover 또는 type=googleNews와 함께 사용해야 합니다. 페이지별로 그룹화하거나 페이지별로 필터링하거나 다른 searchAppearance로 필터링하는 경우 byNewsShowcasePanel로 집계할 수 없습니다.
  • 'byPage': URI로 값을 집계합니다.
  • 'byProperty': 속성별로 값을 집계합니다. type=discover 또는 type=googleNews에서 지원되지 않음
rowLimit integer [선택사항. 유효한 범위는 1~25,000이고 기본값은 1,000입니다.] 반환할 최대 행 수입니다. 결과를 탐색하려면 startRow 오프셋을 사용하세요.
startRow integer [선택사항, 기본값은 0] 응답에서 첫 번째 행의 0부터 시작하는 색인입니다. 음수가 아닌 숫자여야 합니다. startRow가 쿼리 결과 수를 초과하면 행이 0개인 성공적인 응답이 반환됩니다.
dataState string [선택사항] 'all' (대소문자를 구분하지 않음)인 경우 데이터에 최신 데이터가 포함됩니다. '최종' (대소문자를 구분하지 않음)이거나 이 매개변수가 생략된 경우 반환되는 데이터에는 최종 데이터만 포함됩니다.

응답

결과는 요청에 지정된 측정기준에 따라 그룹화됩니다. 측정기준 값이 동일한 모든 값이 단일 행으로 그룹화됩니다. 예를 들어 국가 측정기준별로 그룹화하면 'usa'에 대한 모든 결과가 함께 그룹화되고 'mdv'에 대한 모든 결과는 함께 그룹화됩니다. 국가 및 기기별로 그룹화한 경우 'usa, 태블릿'에 대한 모든 검색결과가 그룹화되고 'usa, mobile'에 대한 모든 검색결과도 그룹화됩니다. 클릭수, 노출수 등의 계산 방식 및 의미를 자세히 알아보려면 검색 애널리틱스 보고서 문서를 참고하세요.

날짜별로 그룹화하는 경우 결과가 날짜별로 오름차순 (오래된 항목순, 최근 날짜순)으로 정렬되지 않는 한 결과는 클릭수를 기준으로 내림차순으로 정렬됩니다. 두 행 사이에 연결이 있는 경우 정렬 순서는 임의적입니다.

반환될 수 있는 최대 값 수를 알아보려면 요청의 rowLimit 속성을 참조하세요.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
속성 이름 값 설명 Notes
rows[] list 쿼리에 지정된 순서대로 키 값별로 그룹화된 행 목록입니다.
rows[].keys[] list 요청에 지정된 순서대로 요청의 측정기준에 따라 그룹화된 행의 측정기준 값 목록입니다.
rows[].clicks double 행의 클릭수입니다.
rows[].impressions double 행의 노출수입니다.
rows[].ctr double 행의 클릭률 (CTR)입니다. 값의 범위는 0~1.0입니다.
rows[].position double 검색결과의 평균 게재순위입니다.
responseAggregationType string 결과를 집계한 방식입니다.사이트와 페이지별로 데이터를 계산하는 방식이 어떻게 다른지 알아보려면 도움말 문서를 참조하세요.

사용 가능한 값은 다음과 같습니다.
  • "auto"
  • 'byPage': 페이지별로 집계한 결과입니다.
  • 'byProperty': 속성별로 집계한 결과입니다.

사용해 보기

아래의 API 탐색기를 사용하여 실시간 데이터를 대상으로 이 메소드를 호출하고 응답을 확인해 보세요.