애널리틱스 Reporting API v4 개발자 가이드입니다. API에 대한 자세한 참조는 API 참조를 확인하세요.
보고서
Analytics Reporting API v4는 Reports 리소스에 액세스하기 위한 batchGet 메서드를 제공합니다.
다음 섹션에서는 batchGet의 요청 본문 구조와 batchGet의 응답 본문 구조를 설명합니다.
요청 본문
Analytics Reporting API v4를 사용하여 데이터를 요청하려면 다음과 같은 최소 요구사항이 포함된 ReportRequest 객체를 구성해야 합니다.
- viewId 필드의 유효한 보기 ID
- dateRanges 필드에 하나 이상의 유효한 항목이 있어야 합니다.
- metrics 입력란에 유효한 항목이 하나 이상 있어야 합니다.
보기 ID를 찾으려면 계정 요약 메서드를 쿼리하거나 계정 탐색기를 사용하세요.
기간이 제공되지 않으면 기본 기간은 {"startDate": "7daysAgo", "endDate": "yesterday"}입니다.
다음은 최소 필수 필드가 포함된 샘플 요청입니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
batchGet 메서드는 최대 5개의 ReportRequest 객체를 허용합니다. 모든 요청의 dateRange, viewId, segments, samplingLevel, cohortGroup는 동일해야 합니다.
응답 본문
API 요청의 응답 본문은 보고서 객체의 배열입니다. 보고서 구조는 보고서의 측정기준 및 측정항목, 데이터 유형을 설명하는 ColumnHeader 객체에 정의됩니다. 측정기준 및 측정항목의 값은 data 필드에 지정됩니다.
다음은 위 샘플 요청에 대한 샘플 응답입니다.
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
측정항목
측정항목은 정량적 측정치입니다. 모든 요청에는 하나 이상의 Metric 객체가 필요합니다.
다음 예에서는 batchGet 메서드에 Sessions 측정항목을 제공하여 지정된 기간의 총 세션수를 가져옵니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
측정기준 및 측정항목 탐색기 또는 Metadata API를 사용하여 사용 가능한 측정기준 및 측정항목의 목록을 가져올 수 있습니다.
필터링
batchGet 요청을 제출할 때 특정 기준을 충족하는 측정항목만 반환하도록 요청할 수 있습니다. 측정항목을 필터링하려면 요청 본문에서 하나 이상의 MetricFilterClauses를 지정하고 각 MetricFilterClause에서 하나 이상의 MetricFilters를 정의합니다.
각 MetricFilter에서 다음 값을 지정합니다.
metricNamenotoperatorcomparisonValue
{metricName}가 측정항목을 나타내고 {operator}는 operator, {comparisonValue}는 comparisonValue를 나타냅니다. 그러면 필터는 다음과 같이 작동합니다.
if {metricName} {operator} {comparisonValue}
return the metric
not에 true를 지정하면 필터는 다음과 같이 작동합니다.
if {metricName} {operator} {comparisonValue}
do not return the metric
다음 예에서 batchGet는 값이 2보다 큰 페이지 조회수만 반환합니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
표현
측정항목 표현식은 기존 측정항목에 정의하는 수학적 표현식입니다. 동적 계산된 측정항목처럼 작동합니다. 측정항목 표현식을 나타내는 별칭을 정의할 수 있습니다. 예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
주문
측정항목 값을 기준으로 결과를 정렬하는 방법은 다음과 같습니다.
다음 예에서 batchGet는 먼저 세션 기준으로 정렬된 측정항목을 반환한 후 페이지 조회수를 기준으로 내림차순으로 정렬하여 반환합니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
크기
측정기준은 사용자, 사용자 세션 및 액션의 특징을 설명합니다.
예를 들어 도시 측정기준은 세션의 특성을 설명하고 각 세션이 시작된 도시 ('파리' 또는 '뉴욕')를 나타냅니다.
batchGet 요청에서 측정기준 객체를 0개 이상 지정할 수 있습니다. 예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
필터링
batchGet 요청을 제출할 때 특정 기준을 충족하는 측정기준만 반환하도록 요청할 수 있습니다. 측정기준을 필터링하려면 요청 본문에서
DimensionsFilterClauses를
1개 이상 지정하고 각 DimensionsFilterClause에서
DimensionsFilters를 하나 이상 정의합니다.
각 DimensionsFilters에서 다음 값을 지정합니다.
dimensionNamenotoperatorexpressionscaseSensitive
{dimensionName}은 측정기준을, {operator}는 operator, {expressions}는 expressions를 나타냅니다. 그러면 필터는 다음과 같이 작동합니다.
if {dimensionName} {operator} {expressions}
return the dimension
not에 true를 지정하면 필터는 다음과 같이 작동합니다.
if {dimensionName} {operator} {expressions}
do not return the dimension
다음 예에서 batchGet는 Chrome 브라우저의 페이지 조회수와 세션을 반환합니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
주문
측정기준 값을 기준으로 결과를 정렬하는 방법은 다음과 같습니다.
예를 들어 다음 batchGet는 국가를 기준으로 정렬된 다음 브라우저별로 정렬된 측정기준을 반환합니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
히스토그램 버킷
정수 값이 있는 차원의 경우, 값을 범위로 버케팅하여 특성을 더 쉽게 이해할 수 있습니다. histogramBuckets 필드를 사용하여 결과 버킷의 범위를 정의하고 HISTOGRAM_BUCKET를 주문 유형으로 지정합니다. 예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
여러 기간
Google 애널리틱스 Reporting API v4를 사용하면 단일 요청으로 여러 기간의 데이터를 가져올 수 있습니다. 요청에서 기간을 1개 또는 2개 지정하든 관계없이 데이터는 dateRangeValue 객체에 반환됩니다. 예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
델타값 정렬
두 기간의 측정항목 값을 요청할 때 기간 내 측정항목 값의 차이를 기준으로 결과를 정렬할 수 있습니다. 예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
날짜 측정기준 동작
날짜 또는 시간 관련 측정기준을 요청하면 DateRangeValue 객체에 해당 범위에 속하는 날짜의 값만 포함됩니다. 지정된 기간에 포함되지 않은 다른 모든 값은 0이 됩니다.
예를 들어 1월과 2월의 두 기간으로 된 ga:date 측정기준과 ga:sessions 측정항목에 대한 요청이 있다고 가정해 보겠습니다.
1월의 요청된 데이터에 대한 응답에서 2월의 값은 0이 되고, 2월의 요청된 데이터에 대한 응답에서 1월의 값은 0이 됩니다.
1월 보고서
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
2월 보고서
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
세그먼트
애널리틱스 데이터의 하위 집합을 요청하려면 세그먼트를 사용하세요. 예를 들어 한 세그먼트에서 특정 국가나 도시의 사용자를 정의하고 다른 세그먼트에서 사이트의 특정 부분을 방문하는 사용자를 정의할 수 있습니다. 필터는 조건을 충족하는 행만 반환하지만 세그먼트는 세그먼트가 포함된 조건을 충족하는 사용자, 세션 또는 이벤트의 하위 집합을 반환합니다.
세그먼트를 사용하여 요청할 때는 다음을 확인하세요.
batchGet메서드 내의 모든 ReportRequest에는 동일한 세그먼트 정의가 포함되어야 합니다.- 측정기준 목록에
ga:segment를 추가합니다.
예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
세그먼트가 포함된 요청의 추가 예는 샘플을 참고하세요.
세그먼트 ID
segmentId 필드를 사용하여 세그먼트를 요청합니다.
세그먼트를 요청하는 데 segmentId와 dynamicSegment를 모두 사용할 수는 없습니다.
예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
샘플링
샘플링은 데이터 결과에 영향을 미칠 수 있으며, 이는 API에서 반환된 값이 웹 인터페이스와 일치하지 않는 일반적인 이유입니다. samplingLevel 필드를 사용하여 원하는 샘플 크기를 설정합니다.
- 샘플링 크기를 줄여 빠른 응답을 받으려면 값을
SMALL로 설정합니다. - 더 정확하면서도 느린 응답을 받으려면 값을
LARGE로 설정합니다. - 속도와 정확성의 균형을 이루는 응답의 경우 값을
DEFAULT로 설정합니다.
예를 들면 다음과 같습니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
보고서에 샘플링된 데이터가 포함된 경우 Analytics Reporting API v4는 samplesReadCounts 및 samplingSpaceSizes 필드를 반환합니다.
결과가 샘플링되지 않으면 이 필드가 정의되지 않습니다.
다음은 기간이 두 개 있는 요청에서 샘플링된 데이터가 포함된 응답 예입니다. 결과는 약 1,500만 개의 세션인 샘플링 공간 크기의 약 500,000개의 샘플로 계산되었습니다.
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
페이지로 나누기
Analytics Reporting API v4는 pageToken 및 pageSize 필드를 사용하여 여러 페이지에 걸쳐 있는 응답 결과를 페이지로 나눕니다. reports.batchGet 요청에 대한 응답의 nextPageToken 매개변수에서 pageToken를 가져옵니다.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
다음 단계
지금까지 보고서 만들기의 기본 사항을 살펴보았으므로 이제 API v4의 고급 기능을 살펴보겠습니다.