애널리틱스 Reporting API v4 개발자 가이드입니다. API에 대한 자세한 내용은 API 참조를 확인하세요.
보고서
애널리틱스 Reporting API v4에서는 Reports 리소스에 액세스하는 batchGet 메서드를 제공합니다.
다음 섹션에서는 batchGet의 요청 본문 구조와 batchGet의 응답 본문 구조를 설명합니다.
요청 본문
Analytics Reporting API v4를 사용하여 데이터를 요청하려면 다음과 같은 최소 요구사항이 있는 ReportRequest 객체를 구성해야 합니다.
- viewId 필드의 유효한 뷰 ID
- dateRanges 필드에 유효한 항목이 1개 이상 있습니다.
- 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 메서드는 ReportRequest 객체를 최대 5개까지 허용합니다. 모든 요청은 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 객체가 하나 이상 필요합니다.
다음 예시에서는 지정된 기간의 총 세션 수를 가져오기 위해 Sessions 측정항목을 batchGet 메서드에 제공합니다.
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에서 MetricFilter를 하나 이상 정의합니다.
각 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 요청을 제출할 때 특정 기준을 충족하는 측정기준만 반환하도록 요청할 수 있습니다. 측정기준을 필터링하려면 요청 본문에서 하나 이상의 DimensionFilterClauses를 지정하고 각 DimensionsFilterClause에서 하나 이상의 DimensionFilter를 정의합니다.
각 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월의 값은 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"
}
]
}
보고서에 샘플링된 데이터가 포함된 경우 애널리틱스 Reporting API v4에서 samplesReadCounts 및 samplingSpaceSizes 필드를 반환합니다.
결과가 샘플링되지 않으면 이 필드가 정의되지 않습니다.
다음은 기간이 2개인 요청의 샘플 데이터가 포함된 응답 예입니다. 결과는 약 1500만 개의 세션에 해당하는 샘플링 공간 크기의 50만 개 샘플에서 계산되었습니다.
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
페이지로 나누기
애널리틱스 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의 고급 기능을 살펴보겠습니다.