승인 필요
정의한 필터와 매개변수로 검색 트래픽 데이터를 쿼리합니다. 메서드는 정의한 행 키 (측정기준)로 그룹화된 0개 이상의 행을 반환합니다. 1일 이상의 기간을 정의해야 합니다.
날짜가 측정기준 중 하나인 경우 데이터가 없는 날짜는 결과 목록에서 생략됩니다. 데이터가 있는 날짜를 알아보려면 관심 있는 기간에 대해 날짜별로 그룹화된 필터 없이 쿼리를 실행합니다.
결과는 클릭수를 기준으로 내림차순으로 정렬됩니다. 두 행의 클릭수가 같으면 임의의 방식으로 정렬됩니다.
이 메서드를 호출하는 Python 샘플을 참고하세요.
API는 Search Console의 내부 제한에 의해 제한되며 모든 데이터 행이 아닌 상위 데이터 행을 반환하도록 보장합니다.
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
}| 속성 이름 | 값 | 설명 | 참고 |
|---|---|---|---|
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" 및 "hour"를 사용할 수 있습니다. 그룹화 측정기준 값이 결합되어 각 결과 행의 고유 키를 만듭니다. 측정기준이 지정되지 않으면 모든 값이 단일 행으로 결합됩니다. 그룹화할 수 있는 측정기준 수에는 제한이 없지만 동일한 측정기준으로 두 번 그룹화할 수는 없습니다. 예: [country, device] | |
searchType |
string |
지원 중단됨, 대신 type 사용
|
|
type |
string |
[선택사항] 결과를 다음 유형으로 필터링합니다.
|
|
dimensionFilterGroups[] |
list |
[선택사항] 측정기준 그룹화 값에 적용할 0개 이상의 필터 그룹입니다. 응답에 행이 반환되려면 모든 필터 그룹이 일치해야 합니다. 단일 필터 그룹 내에서 모든 필터가 일치해야 하는지 또는 하나 이상이 일치해야 하는지 지정할 수 있습니다. | |
dimensionFilterGroups[].groupType |
string |
이 그룹의 모든 필터가 true를 반환해야 하는지('and') 또는 하나 이상이 true를 반환해야 하는지 (아직 지원되지 않음)입니다.
사용 가능한 값은 다음과 같습니다.
|
|
dimensionFilterGroups[].filters[] |
list |
[선택사항] 행에 대해 테스트할 0개 이상의 필터입니다. 각 필터는
측정기준 이름, 연산자, 값으로 구성됩니다. 최대 길이는 4,096자(영문 기준)입니다. 예:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
이 필터가 적용되는 측정기준입니다. 이 측정기준으로 그룹화하지 않더라도 여기에 나열된 측정기준으로 필터링할 수 있습니다.
사용 가능한 값은 다음과 같습니다.
|
|
dimensionFilterGroups[].filters[].operator |
string |
[선택사항] 지정된 값이 행의 측정기준 값과 일치해야 하는지 (또는 일치하지 않아야 하는지)입니다.
사용 가능한 값은 다음과 같습니다.
|
|
dimensionFilterGroups[].filters[].expression |
string |
연산자에 따라 일치시키거나 제외할 필터의 값입니다. | |
aggregationType |
string |
[선택사항] 데이터가 집계되는 방식입니다. 속성별로 집계되는 경우 동일한 속성의 모든 데이터가 집계되고 페이지별로 집계되는 경우 모든 데이터가 표준 URI별로 집계됩니다. 페이지별로 필터링하거나 그룹화하는 경우 '자동'을 선택합니다. 그렇지 않으면 데이터를 계산하려는 방식에 따라 속성별 또는 페이지별로 집계할 수 있습니다. 도움말 문서를 참고하여 사이트별 데이터 계산 방식과 페이지별 데이터 계산 방식의 차이점을 알아보세요. 참고: 페이지별로 그룹화하거나 필터링하는 경우 속성별로 집계할 수 없습니다. '자동' 이외의 값을 지정하면 결과의 집계 유형이 요청된 유형과 일치합니다. 또는 유효하지 않은 유형을 요청하면 오류가 발생합니다. 요청된 유형이 유효하지 않은 경우 API는 집계 유형을 변경하지 않습니다. 사용 가능한 값은 다음과 같습니다.
|
|
rowLimit |
integer |
[선택사항, 유효한 범위는 1~25,000, 기본값은 1,000] 반환할 최대 행 수입니다. 결과를 페이지 단위로 표시하려면 startRow 오프셋을 사용합니다. |
|
startRow |
integer |
[선택사항, 기본값은 0] 응답의 첫 번째 행에 대한 0부터 시작하는 색인입니다. 음수가 아닌 숫자여야 합니다. startRow가 쿼리 결과 수를 초과하면 응답은 행이 0개인 성공적인 응답이 됩니다. |
|
dataState |
string |
[선택사항] 'all'(대소문자 구분 안 함)인 경우 데이터에 최신 데이터가 포함됩니다. 'final'(대소문자 구분 안 함)이거나 이 매개변수가 생략된 경우 반환된 데이터에는 완료된 데이터만 포함됩니다. 'hourly_all'(대소문자 구분 안 함)인 경우 데이터에 시간별 분석이 포함됩니다. 이는 시간별 데이터에 일부 데이터가 포함되어 있으며 HOUR API 측정기준으로 그룹화할 때 사용해야 함을 나타냅니다. |
응답
결과는 요청에 지정된 측정기준에 따라 그룹화됩니다. 동일한 측정기준 값 집합을 가진 모든 값은 단일 행으로 그룹화됩니다. 예를 들어 국가 측정기준으로 그룹화하는 경우 'usa'의 모든 결과가 함께 그룹화되고 'mdv'의 모든 결과가 함께 그룹화되는 식입니다. 국가 및 기기로 그룹화한 경우 'usa, tablet'의 모든 결과가 그룹화되고 'usa, mobile'의 모든 결과가 그룹화되는 식입니다. 클릭수, 노출수 등의 계산 방식과 의미에 관한 자세한 내용은 검색 애널리틱스 보고서 문서를 참고하세요.
결과는 클릭수를 기준으로 내림차순으로 정렬됩니다. 단, 날짜별로 그룹화하는 경우 결과는 날짜를 기준으로 오름차순으로 정렬됩니다 (가장 오래된 날짜가 먼저, 가장 최근 날짜가 마지막). 두 행이 동률인 경우 정렬 순서는 임의로 지정됩니다.
반환할 수 있는 최대 값은 요청의 rowLimit 속성을 참고하세요.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| 속성 이름 | 값 | 설명 | 참고 |
|---|---|---|---|
rows[] |
list |
쿼리에 지정된 순서대로 키 값으로 그룹화된 행 목록입니다. | |
rows[].keys[] |
list |
요청에 지정된 순서대로 요청의 측정기준에 따라 그룹화된 해당 행의 측정기준 값 목록입니다. | |
rows[].clicks |
double |
행의 클릭수입니다. | |
rows[].impressions |
double |
행의 노출수입니다. | |
rows[].ctr |
double |
행의 클릭률 (CTR)입니다. 값의 범위는 0~1.0(포함)입니다. | |
rows[].position |
double |
검색 결과의 평균 게재순위입니다. | |
responseAggregationType |
string |
결과가 집계된 방식입니다.사이트별 데이터 계산 방식과 페이지별 데이터 계산 방식의 차이점은 도움말 문서를 참고하세요.
사용 가능한 값은 다음과 같습니다.
|
|
metadata |
object |
데이터 상태에 관한 컨텍스트를 제공하는 쿼리 결과와 함께 반환될 수 있는 객체입니다. 최근 데이터를 요청할 때 ( 이 객체에 제공된 모든 날짜와 시간은 이 객체 내에서 반환되는 특정 필드는 요청에서 데이터를 그룹화한 방식에 따라 다릅니다:
|
기능을 사용해 보세요.
아래의 API 탐색기를 사용하여 실시간 데이터를 대상으로 이 메소드를 호출하고 응답을 확인해 보세요.