이 문서에서는 다채널 유입경로 Reporting API의 쿼리 및 응답에 대한 전체 참조를 제공합니다.
소개
다채널 유입경로 Reporting API를 사용하면 Google 애널리틱스 다채널 유입경로 보고서 데이터를 요청할 수 있습니다. 모든 보고서는 추적 코드가 애널리틱스로 다시 전송된 데이터에서 파생된 통계로 구성되며, 측정기준과 측정항목으로 구성됩니다. 측정기준 및 측정항목의 조합을 선택하여 Reporting API를 통해 나만의 사양에 맞게 맞춤설정된 보고서를 만들 수 있습니다.
API에는 보고서 데이터를 요청하는 단일 메서드(report.get)가 포함되어 있습니다. 이 메서드를 사용하면 데이터를 검색하려는 뷰(프로필)에 해당하는 테이블 ID를 제공할 수 있습니다. 또한 다음을 지정합니다.
- 측정기준과 측정항목의 조합입니다.
- 기간
- 반환되는 데이터를 제어하는 옵션 매개변수 집합
API를 통해 REST 엔드포인트에서 report.get 메서드를 사용할 수 있습니다.https://www.googleapis.com/analytics/v3/data/mcf 다음 섹션에서는 샘플 요청을 보여주며 각 매개변수를 설명합니다.
요청
API는 데이터를 요청하는 단일 메서드를 제공합니다.
analytics.data.mcf.get()
API를 REST 엔드포인트로 쿼리할 수도 있습니다.
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
각 URL 쿼리 매개변수는 URL로 인코딩되어야 하는 API 쿼리 매개변수를 지정합니다.
다중 채널 유입경로 Reporting API에 대한 모든 요청은 가능하면 OAuth 2.0을 통해 승인해야 합니다.
쿼리 매개변수 요약
다음 표에는 다채널 유입경로 Reporting API에서 허용하는 모든 쿼리 매개변수가 요약되어 있습니다. 각 매개변수 이름을 클릭하여 자세한 설명을 확인합니다.
이름 | 값 | 필수 | 요약 |
---|---|---|---|
ids |
string |
예 | ga:XXXX 형식의 고유 테이블 ID입니다. 여기서 XXXX는 쿼리가 데이터를 검색하는 애널리틱스 보기 (프로필) ID입니다. |
start-date |
string |
예 |
애널리틱스 데이터를 가져오기 위한 시작일입니다. 요청은 시작 형식을 YYYY-MM-DD 또는 상대 날짜로 지정할 수 있습니다(예: today , yesterday 또는 NdaysAgo . 여기서 N 은 양의 정수입니다.
|
end-date |
string |
예 |
애널리틱스 데이터를 가져오는 종료일입니다. 요청은 종료 형식을 YYYY-MM-DD 또는 상대 날짜로 지정할 수 있습니다 (예:
today , yesterday 또는 NdaysAgo . 여기서 N 은 양의 정수입니다.
|
metrics |
string |
예 | 쉼표로 구분된 측정항목의 목록입니다(예: mcf:totalConversions,mcf:totalConversionValue ).
유효한 쿼리는 측정항목을 1개 이상 지정해야 합니다. |
dimensions |
string |
아니요 | 다중 채널 유입경로 보고서의 쉼표로 구분된 측정기준(예: mcf:source,mcf:keyword )의 목록입니다. |
sort |
string |
아니요 | 쉼표로 구분된 측정기준 및 측정항목의 목록으로, 반환된 데이터의 정렬 순서와 정렬 방향을 나타냅니다. |
filters |
string |
아니요 | 요청에 대해 반환되는 데이터를 제한하는 측정기준 또는 측정항목 필터입니다. |
samplingLevel |
string |
아니요 | 원하는 샘플링 수준 허용되는 값은 다음과 같습니다.
|
start-index |
integer |
아니요 | 가져올 데이터의 첫 번째 행이며 1부터 시작합니다.
이 매개변수를 max-results 매개변수와 함께 페이지로 나누기 메커니즘으로 사용합니다. |
max-results |
integer |
아니요 | 응답에 포함할 최대 행 수입니다. |
쿼리 매개변수 세부정보
ids
ids=ga:12345
ga:
네임스페이스의 연결입니다. Google 애널리틱스 관리 API의 보기 (프로필) 리소스에 id
를 제공하는 analytics.management.profiles.list
메서드를 사용하여 보고서의 보기 (프로필) ID를 검색할 수 있습니다.
시작일
start-date=2011-10-01
start-date
및 end-date
매개변수를 포함하지 않으면 서버에서 오류를 반환합니다.
날짜 값은 YYYY-MM-DD
패턴을 사용하여 특정 날짜에 할당되거나 today
, yesterday
또는 NdaysAgo
패턴을 사용하여 상대적일 수 있습니다.
값은 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
과 일치해야 합니다.
start-date
은 2011-01-01
입니다.
start-date
에는 상한이 없습니다.상대적 날짜를 사용한 지난 7일 (어제부터)의 기간 예시:
&start-date=7daysAgo &end-date=yesterday
종료일
end-date=2011-10-31
start-date
및 end-date
매개변수를 포함하지 않으면 서버에서 오류를 반환합니다.
날짜 값은 YYYY-MM-DD
패턴을 사용하여 특정 날짜에 할당되거나 today
, yesterday
또는 NdaysAgo
패턴을 사용하여 상대적일 수 있습니다.
값은 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
과 일치해야 합니다.
end-date
은 2005-01-01
입니다. end-date
에는 상한 제한이 없습니다. 상대적 날짜를 사용한 지난 10일 (오늘부터)의 기간 예시:
&start-date=9daysAgo &end-date=today
dimensions
dimensions=mcf:source,mcf:keyword
측정기준 매개변수는 다채널 유입경로 보고서의 기본 데이터 키(예: mcf:source
또는 mcf:medium
)를 정의합니다.
측정기준을 사용하여 전환 측정항목을 분류하세요. 예를 들어 사이트에 대한 총 전환수를 요청할 수 있지만 매체로 분류된 전환수를 요청하는 것이 더 흥미로울 수 있습니다.
이 경우 자연 검색, 추천, 이메일 등을 통해 발생한 전환수가 표시됩니다.
데이터 요청에서 dimensions
를 사용할 때 다음 제약 조건을 알고 있어야 합니다.
- 검색어당 최대 7개의 측정기준을 제공할 수 있습니다.
- 측정기준으로만 구성된 쿼리는 보낼 수 없습니다. 요청된 측정기준과 측정항목을 하나 이상의 측정항목과 결합해야 합니다.
사용할 수 없는 값
측정기준의 값을 확인할 수 없는 경우 애널리틱스에서는 설정되지 않은 특수 문자열을 사용합니다.
측정항목
metrics=mcf:totalConversions,mcf:totalConversionValue
사이트에 발생한 사용자 활동에 대해 집계된 통계(예: 총 전환수, 총 전환 가치)입니다.
쿼리에 dimensions
매개변수가 없으면 반환된 측정항목은 요청된 기간 동안 집계 값(예: 전체 총 전환 가치)을 제공합니다. 측정기준이 요청되면 값은 측정기준 값을 기준으로 분류됩니다.
예를 들어 mcf:source
로 요청된 mcf:totalConversions
은 소스당 총 전환수를 반환합니다.
측정항목을 요청할 때는 다음 사항에 주의하세요.
- 모든 요청은 측정항목을 하나 이상 제공해야 합니다. 요청은 측정기준만으로 구성될 수 없습니다.
- 쿼리당 최대 10개의 측정항목을 제공할 수 있습니다.
sort
sort=mcf:source,mcf:medium
반환된 데이터의 정렬 순서와 정렬 방향을 나타내는 측정항목 및 측정기준 목록입니다.
- 정렬 order는 나열된 측정항목과 측정기준의 왼쪽에서 오른쪽 순서로 지정됩니다.
- 방향을 정렬하면 기본값이 오름차순으로 설정되며 요청된 필드에 빼기 기호 (
-
) 프리픽스를 사용해 내림차순으로 변경할 수 있습니다.
쿼리 결과를 정렬하면 데이터에 대해 다른 질문을 할 수 있습니다. 예를 들어 '내 주요 전환 소스는 무엇이고 어떤 매체를 통해 연결되어 있나요?'라는 질문에 답하기 위해
다음 매개변수를 사용하여 쿼리를 수행할 수 있습니다. 먼저 mcf:source
를 기준으로 정렬한 후 mcf:medium
를 기준으로 오름차순으로 정렬합니다.
sort=mcf:source,mcf:medium
다음 질문을 사용하여 관련 질문의 답변을 구할 수 있습니다. 먼저 mcf:medium
를 기준으로 정렬한 다음
mcf:source
를 기준으로 오름차순으로 정렬합니다.
sort=mcf:medium,mcf:source
sort
매개변수를 사용할 때 다음 사항에 유의하세요.
dimensions
또는metrics
매개변수에서 사용한 측정기준 또는 측정항목 값만 정렬하세요. 요청이 측정기준 또는 측정항목 매개변수에 지정되지 않은 필드를 기준으로 정렬되면 오류가 발생합니다.- 기본적으로 문자열은 en-US 언어의 오름차순으로 정렬됩니다.
- 기본적으로 숫자는 오름차순으로 정렬됩니다.
- 기본적으로 날짜는 날짜별로 오름차순으로 정렬됩니다.
필터
filters=mcf:medium%3D%3Dreferral
filters
쿼리 문자열 매개변수는 요청에서 반환되는 데이터를 제한합니다. filters
매개변수를 사용하려면 필터링할 측정기준 또는 측정항목과 필터 표현식을 입력합니다. 예를 들어 다음 쿼리는 뷰 (프로필) 12134
에 mcf:totalConversions
및 mcf:source
를 요청하며, 여기서 mcf:medium
측정기준은 referral
문자열입니다.
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
자세한 내용은 Core Reporting API 참조를 참고하세요.
샘플링 수준
samplingLevel=DEFAULT
DEFAULT
— 속도와 정확성이 균형을 이루는 샘플 크기로 응답을 반환합니다.FASTER
— 더 작은 샘플 크기로 빠른 응답을 반환합니다.HIGHER_PRECISION
— 큰 샘플 크기를 사용하여 더 정확한 응답을 반환하지만 이 경우 응답 속도가 느려질 수 있습니다.
DEFAULT
샘플링 수준이 사용됩니다.최대 결과
max-results=100
이 응답에 포함할 최대 행 수입니다. 이 속성을 start-index
와 함께 사용하여 일부 요소를 검색하거나 단독으로 사용하여 첫 번째 요소부터 반환된 요소 수를 제한할 수 있습니다.
max-results
을 지정하지 않으면 쿼리는 기본적으로 최대 1, 000개의 행을 반환합니다.
다채널 유입경로 Reporting API는 요청 수와 관계없이 요청당 최대 10,000개의 행을 반환합니다. 또한 측정기준 세그먼트가 예상보다 적으면 요청된 행보다 적은 행을 반환할 수도 있습니다. 예를 들어 mcf:medium
에 사용할 수 있는 값은 300개 미만이므로 매체를 기준으로만 분류할 경우 max-results
을 더 높은 값으로 설정해도 300개가 넘는 행을 얻을 수 없습니다.
응답
요청이 성공하면 이 요청은 아래에 정의된 JSON 구조를 사용하여 응답 본문을 반환합니다.
참고: '결과'라는 용어는 쿼리와 일치하는 전체 행 집합을 나타내고, '응답'은 현재 결과 페이지에서 반환되는 행 집합을 나타냅니다. itemsPerPage에 설명된 대로 총 결과의 결과가 현재 응답의 페이지 크기보다 클 경우 달라질 수 있습니다.
응답 형식
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
응답 필드
응답 본문 구조의 속성은 다음과 같이 정의됩니다.
속성 이름 | 값 | 설명 |
---|---|---|
kind |
string |
리소스 유형입니다. 값은 "analytics#mcfData"입니다. |
id |
string |
이 데이터 응답의 ID입니다. |
query |
object |
이 객체에는 쿼리에 매개변수로 전달된 모든 값이 포함되어 있습니다. 각 필드의 의미는 해당 쿼리 매개변수에 설명되어 있습니다. |
query.start-date |
string |
시작일 |
query.end-date |
string |
종료일 |
query.ids |
string |
고유한 테이블 ID입니다. |
query.dimensions[] |
list |
애널리틱스 측정기준 목록입니다. |
query.metrics[] |
list |
분석 측정항목 목록입니다. |
query.sort[] |
list |
데이터가 정렬되는 측정항목 또는 측정기준의 목록입니다. |
query.filters |
string |
쉼표로 구분된 측정항목 또는 측정기준 필터 목록입니다. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
행의 시작 색인입니다. 기본값은 1입니다. |
query.max-results |
integer |
페이지당 최대 결과 수 |
startIndex |
integer |
start-index 쿼리 매개변수로 지정된 행의 시작 색인입니다. 기본값은 1입니다. |
itemsPerPage |
integer |
반환된 실제 행 수와 상관없이 응답에 포함할 수 있는 최대 행 수입니다. max-results 쿼리 매개변수가 지정된 경우 itemsPerPage 값은 max-results 또는 10,000 중 더 작은 값입니다. itemsPerPage 의 기본값은 1000입니다.
|
totalResults |
integer |
응답에서 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 다량의 행을 생성하는 쿼리의 경우 totalResults 이 itemsPerPage 보다 클 수 있습니다.
대규모 쿼리의 경우 totalResults 및 itemsPerPage 에 관한 자세한 설명은 Paging을 참고하세요.
|
selfLink |
string |
이 데이터 쿼리의 결과 페이지 링크 |
previousLink |
string |
이 데이터 쿼리에 대한 이전 검색결과 페이지 링크 |
nextLink |
string |
이 데이터 쿼리에 대한 다음 결과 페이지 링크 |
profileInfo |
object |
데이터가 요청된 뷰 (프로필)에 관한 정보입니다. 보기 (프로필) 데이터는 Google 애널리틱스 관리 API를 통해 사용할 수 있습니다. |
profileInfo.profileId |
string |
보기(프로필) ID(예: 1174 ) |
profileInfo.accountId |
string |
이 보기(프로필)가 속한 계정 ID입니다(예: 30481 ). |
profileInfo.webPropertyId |
string |
이 보기(프로필)가 속한 웹 속성 ID입니다(예: UA-30481-1 ). |
profileInfo.internalWebPropertyId |
string |
이 보기(프로필)가 속한 웹 속성의 내부 ID입니다(예: UA-30481-1 ). |
profileInfo.profileName |
string |
보기 (프로필)의 이름입니다. |
profileInfo.tableId |
string |
보기 (프로필)의 테이블 ID로, 'ga:" 다음에 뷰 (프로필) ID가 옵니다. |
containsSampledData |
boolean |
응답에 샘플링된 데이터가 포함된 경우 true입니다. |
sampleSize |
string |
샘플링된 데이터를 계산하는 데 사용된 샘플 수입니다. |
sampleSpace |
string |
전체 샘플링 공간 크기 이는 샘플이 선택된 총 사용 가능한 샘플 공간 크기를 나타냅니다. |
columnHeaders[] |
list |
측정기준 이름과 측정항목 이름이 나열된 열 헤더 측정기준 및 측정항목의 순서는 metrics 및 dimensions 매개변수를 통해 요청에 지정된 순서와 동일합니다. 헤더 수는 측정기준 수와 측정항목 수를 더한 값입니다. |
columnHeaders[].name |
string |
측정기준 또는 측정항목의 이름입니다. |
columnHeaders[].columnType |
string |
열 유형입니다. 'METRIC' 또는 'METRIC' |
columnHeaders[].dataType |
string |
데이터 유형입니다. 측정기준 열 헤더에는 데이터 유형으로
"STRING" 또는 "MCF_SEQUENCE" 만 있습니다.
측정항목 열 헤더에는 측정항목 값에 대한 데이터 유형(예: "INTEGER" , "DOUBLE" , "CURRENCY" )이 있습니다. |
totalsForAllResults |
object |
측정항목 및 값의 키-값 쌍으로 요청된 측정항목의 총 값입니다. 측정항목 합계 순서는 요청에 지정된 측정항목 순서와 동일합니다. |
rows[] |
list |
데이터 행을 보고하세요. 각 행에는
{ "primitiveValue": "2183" }
{ "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] } |
오류 코드
다중 채널 유입경로 Reporting API는 요청이 성공하면 200
HTTP 상태 코드를 반환합니다. 쿼리 처리 중에 오류가 발생하면 API는 오류 코드와 설명을 반환합니다.
애널리틱스 API를 사용하는 각 애플리케이션은 적절한 오류 처리 로직을 구현해야 합니다. 오류 코드 및 오류 처리 방법에 대한 자세한 내용은 오류 응답 참조 가이드를 참조하세요.
사용해 보기
아래의 API 탐색기를 사용하여 실시간 데이터를 대상으로 이 메소드를 호출하고 응답을 확인해 보세요.
샘플링
Google 애널리틱스는 측정기준과 측정항목의 특정 조합을 즉시 계산합니다. Google 애널리틱스는 적절한 시간 내에 데이터를 반환하기 위해 데이터 샘플만 처리할 수 있습니다.
sampleLevel 매개변수를 설정하여 요청에 사용할 샘플링 수준을 지정할 수 있습니다.
MCF Reporting API 응답에 샘플링된 데이터가 포함된 경우 containsSampledData
응답 필드는 true
입니다.
또한 2개의 속성은 쿼리의 샘플링 수준(sampleSize
및 sampleSpace
)에 대한 정보를 제공합니다.
이 두 값을 통해 쿼리에 사용된 세션의 비율을 계산할 수 있습니다. 예를 들어 sampleSize
가 201,000
이고 sampleSpace
이 220,000
인 경우 보고서는 (201,000/220,000) * 100 = 91.36%를 기반으로 합니다.
샘플링에 관한 일반적인 설명과 Google 애널리틱스에서 사용되는 방법을 알아보려면 샘플링을 참고하세요.
대규모 데이터 결과 처리
쿼리에서 큰 결과 집합을 반환할 것으로 예상되는 경우 아래 가이드라인을 사용하여 API 쿼리를 최적화하고 오류를 방지하며 할당량 오버런을 최소화하세요. API 요청 하나에 최대 7개의 측정기준과 10개의 측정항목을 허용하는 방식으로 성능 기준을 설정합니다. 많은 수의 측정항목과 측정기준을 지정하는 일부 쿼리는 다른 쿼리보다 처리하는 데 시간이 더 오래 걸릴 수 있지만, 요청된 측정항목의 수를 제한하는 것만으로는 쿼리 성능을 개선할 수 없습니다. 대신 최상의 성능을 위해 다음 기법을 사용할 수 있습니다.
쿼리당 측정기준 축소
API를 사용하면 한 요청에 최대 7개의 측정기준을 지정할 수 있습니다. Google 애널리틱스는 이러한 복잡한 쿼리의 결과를 즉석에서 계산해야 하는 경우가 많습니다. 이로 인해 결과 행 수가 많은 경우 특히 시간이 오래 걸릴 수 있습니다. 예를 들어 시간별로 키워드를 쿼리하면 수백만 행의 데이터가 일치할 수 있습니다. 쿼리에서 측정기준의 수를 제한하여 Google 애널리틱스에서 처리해야 하는 행의 수를 줄여 성능을 개선할 수 있습니다.
기간별로 쿼리 분할하기
하나의 긴 기간에 대한 날짜 관련 결과를 훑어보는 대신 한 번에 일주일 또는 하루 동안 별도의 쿼리를 만들어 보세요. 물론, 데이터 세트의 크기가 큰 경우 하루의 데이터에 대한 요청도 max-results
를 반환할 수 있으며, 이 경우 페이징을 피할 수 없습니다. 하지만 어떤 경우든 쿼리의 일치하는 행 수가 max-results
보다 많은 경우 기간을 분리하면 결과를 가져오는 총 시간이 단축될 수 있습니다. 이 접근 방식은 단일 스레드 및 병렬 쿼리 성능을 개선할 수 있습니다.
Paging
결과를 페이징하는 것은 대규모 결과 집합을 관리 가능한 청크로 분할하는 유용한 방법이 될 수 있습니다. totalResults
필드는 일치하는 행의 수를 알려주며 itemsPerPage
는 결과에 반환될 수 있는 최대 행 수를 제공합니다.
totalResults
대 itemsPerPage
의 비율이 높으면 개별 쿼리가 필요한 것보다 더 오래 걸릴 수 있습니다. 표시 목적 등으로 인해 제한된 수의 행만 필요한 경우 max-results
매개변수를 통해 응답 크기에 대한 명시적인 제한을 설정하는 것이 편리할 수 있습니다. 그러나 애플리케이션이 많은 결과를 전부 처리해야 하는 경우에는 허용되는 최대 행을 요청하는 것이 더 효율적일 수 있습니다.
gzip 사용
각 요청에 필요한 대역폭을 줄이는 쉽고 편리한 방법은 gzip 압축을 사용 설정하는 것입니다. 결과를 압축 해제하려면 추가 CPU 시간이 필요하지만 일반적으로 네트워크 비용을 절감할 수 있다는 장점이 있습니다. gzip으로 인코딩된 응답을 받으려면 Accept-Encoding
헤더를 설정하고 gzip
문자열을 포함하도록 사용자 에이전트를 수정해야 합니다.
다음은 gzip 압축을 사용 설정하기 위한 올바른 형식의 HTTP 헤더의 예입니다.
Accept-Encoding: gzip User-Agent: my program (gzip)