Core Reporting API - 참조 가이드

이 문서에서는 Core Reporting API 버전 3.0의 쿼리와 응답에 관한 전체 참조를 제공합니다.

소개

Core Reporting API를 통해 Google 애널리틱스 보고서 데이터를 쿼리합니다. 각 쿼리에는 보기 (프로필) ID, 시작일 및 종료일, 하나 이상의 측정항목이 필요합니다. 측정기준, 필터, 세그먼트와 같은 추가 쿼리 매개변수를 제공하여 쿼리를 미세 조정할 수도 있습니다. 이러한 모든 개념이 함께 작동하는 방식을 이해하려면 개요 가이드를 참조하세요.

요청

API는 데이터를 요청하는 단일 메서드를 제공합니다.

analytics.data.ga.get()

이 메서드는 다양한 클라이언트 라이브러리에 노출되며 쿼리 매개변수를 설정하는 언어별 인터페이스를 포함합니다.

API를 REST-ful 엔드포인트로 쿼리할 수도 있습니다.

Authorization: Bearer {oauth2-token}

GET https://www.googleapis.com/analytics/v3/data/ga
  ?ids=ga:12345
  &start-date=2008-10-01
  &end-date=2008-10-31
  &metrics=ga:sessions,ga:bounces

각 URL 쿼리 매개변수는 URL로 인코딩되어야 하는 API 쿼리 매개변수를 지정합니다.

쿼리 매개변수 요약

다음 표에는 Core 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 예 쉼표로 구분된 측정항목의 목록입니다(예: ga:sessions,ga:bounces).
dimensions string 아니요 애널리틱스 데이터를 위한 쉼표로 구분된 측정기준의 목록(예: ga:browser,ga:city).
sort string 아니요 반환된 데이터의 정렬 순서 및 정렬 방향을 나타내는 쉼표로 구분된 측정기준 및 측정항목의 목록입니다.
filters string 아니요 요청에 대해 반환되는 데이터를 제한하는 측정기준 또는 측정항목 필터입니다.
segment string 아니요 요청에 대해 반환된 데이터를 분류합니다.
samplingLevel string 아니요 원하는 샘플링 수준입니다. 허용되는 값:
  • DEFAULT - 속도와 정확성이 균형을 이루는 샘플 크기로 응답을 반환합니다.
  • FASTER - 샘플 크기가 더 작은 빠른 응답을 반환합니다.
  • HIGHER_PRECISION - 큰 샘플 크기를 사용하여 더 정확한 응답을 반환하지만 이로 인해 응답이 느려질 수 있습니다.
include-empty-rows boolean 아니요 기본값은 true입니다. false로 설정하면 모든 측정항목 값이 0인 행이 응답에서 생략됩니다.
start-index integer 아니요 검색할 첫 번째 데이터 행으로, 1부터 시작합니다. 이 매개변수를 max-results 매개변수와 함께 페이지로 나누기 메커니즘으로 사용합니다.
max-results integer 아니요 응답에 포함할 최대 행 수입니다.
output string 아니요 응답에 반환된 애널리틱스 데이터에 대해 원하는 출력 유형입니다. 허용되는 값은 json 및 dataTable입니다. 기본값은 json입니다.
fields string 아니요 응답에 포함할 필드의 하위 집합을 지정하는 선택기입니다.
prettyPrint string 아니요 들여쓰기와 줄바꿈이 적용된 응답을 반환합니다. 기본값은 false입니다.
userIp string 아니요 API 호출이 이루어지는 최종 사용자의 IP 주소를 지정합니다. IP당 사용량 한도를 설정하는 데 사용됩니다.
quotaUser string 아니요 사용자의 IP 주소를 알 수 없는 경우 userIp를 대체합니다.
access_token string 아니요 OAuth 2.0 토큰을 제공하는 한 가지 방법입니다.
callback string 아니요 응답을 처리하는 자바스크립트 콜백 함수의 이름입니다. JavaScript JSON-P 요청에서 사용됩니다.
key string 아니요 할당량을 가져올 애플리케이션을 지정하는 OAuth 1.0a 승인에 사용됩니다. 예를 들면 key=AldefliuhSFADSfasdfasdfASdf입니다.

쿼리 매개변수 세부정보

ids

ids=ga:12345
필수 항목입니다.
애널리틱스 데이터를 가져오는 데 사용되는 고유 ID입니다. 이 ID는 ga: 네임스페이스를 애널리틱스 보기 (프로필) ID와 연결한 것입니다. Google Analytics Management API의 보기 (프로필) 리소스에 id를 제공하는 analytics.management.profiles.list 메서드를 사용하여 보기 (프로필) ID를 검색할 수 있습니다.

시작일

start-date=2009-04-20
필수 항목입니다.
모든 애널리틱스 데이터 요청은 기간을 지정해야 합니다. 요청에 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는 2005-01-01입니다. 시작일의 상한선은 없습니다.
상대 날짜는 항상 쿼리 당시의 현재 날짜를 기준으로 하며 쿼리에 지정된 뷰 (프로필)의 시간대를 기준으로 합니다.

상대 날짜를 사용한 지난 7일 (어제 시작)의 기간 예시:

  &start-date=7daysAgo
  &end-date=yesterday

종료일

end-date=2009-05-20
필수 항목입니다.
모든 애널리틱스 데이터 요청은 기간을 지정해야 합니다. 요청에 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=ga:browser,ga:city
선택사항입니다.
dimensions 매개변수는 공통 기준(예: ga:browser 또는 ga:city)에 따라 측정항목을 분류합니다. 사이트의 총 페이지 조회수를 요청할 수도 있지만 브라우저별로 세분화된 페이지 조회수를 요청하는 것이 더 흥미로울 수 있습니다. 이 경우 Firefox, Internet Explorer, Chrome 등의 페이지 조회수가 표시됩니다.

데이터 요청에 dimensions를 사용하는 경우 다음 제약 조건에 유의하세요.

  • 모든 검색어에 최대 7개의 측정기준을 제공할 수 있습니다.
  • 측정기준으로만 구성된 쿼리는 전송할 수 없습니다. 요청된 측정기준을 하나 이상의 측정항목과 결합해야 합니다.
  • 동일한 쿼리에서 특정 측정기준만 쿼리할 수 있습니다. 측정기준 및 측정항목 참조의 유효한 조합 도구를 사용하여 함께 사용할 수 있는 측정기준을 확인하세요.

metrics

metrics=ga:sessions,ga:bounces
필수 항목입니다.
클릭수 또는 페이지 조회수와 같이 사이트에서 발생하는 사용자 활동에 관해 집계된 통계입니다. 쿼리에 dimensions 매개변수가 없으면 반환된 측정항목은 요청된 기간 동안 전체 페이지 조회수 또는 총 이탈수와 같은 집계 값을 제공합니다. 하지만 측정기준이 요청되면 값이 측정기준 값을 기준으로 분류됩니다. 예를 들어 ga:country로 요청된 ga:pageviews는 국가별 총 페이지 조회수를 반환합니다. 측정항목을 요청할 때는 다음 사항에 유의하세요.
  • 모든 요청은 측정항목을 1개 이상 제공해야 합니다. 요청은 측정기준으로만 구성될 수 없습니다.
  • 모든 검색어에 대해 최대 10개의 측정항목을 제공할 수 있습니다.
  • 측정기준을 지정하지 않으면 여러 카테고리의 측정항목 조합 대부분을 함께 사용할 수 있습니다.
  • 측정항목은 다른 측정기준 또는 측정항목과 함께 사용할 수 있지만 해당 측정항목에 유효한 조합이 적용되는 경우에만 사용할 수 있습니다. 자세한 내용은 측정기준 및 측정항목 참조를 확인하세요.

sort

sort=ga:country,ga:browser
선택사항입니다.

반환된 데이터의 정렬 순서 및 정렬 방향을 나타내는 측정항목 및 측정기준의 목록입니다.

  • 정렬 순서는 나열된 측정항목 및 측정기준의 왼쪽에서 오른쪽으로 지정됩니다.
  • 정렬 direction은 기본적으로 오름차순으로 되어 있으며 요청된 필드에 빼기 기호 (-) 프리픽스를 사용하여 내림차순으로 변경할 수 있습니다.

쿼리 결과를 정렬하면 데이터에 대해 다양한 질문을 할 수 있습니다. 예를 들어 '인기 국가는 어디이며 가장 많이 사용하는 브라우저는 무엇인가요?'라는 질문에 답변할 수 있습니다. 다음 매개변수를 사용하여 쿼리를 만들 수 있습니다. 먼저 ga:country로 정렬된 후 ga:browser를 기준으로 모두 오름차순으로 정렬됩니다.

sort=ga:country,ga:browser

'인기 브라우저는 무엇이며 브라우저를 가장 많이 사용하는 국가'와 관련된 질문에 답하려면 다음 매개변수를 사용하여 쿼리를 실행하면 됩니다. 먼저 ga:browser로 정렬된 다음 ga:country를 기준으로 오름차순으로 정렬됩니다. 
sort=ga:browser,ga:country

sort 매개변수를 사용할 때는 다음 사항에 유의하세요.

  • dimensions 또는 metrics 매개변수에서 사용한 측정기준 또는 측정항목 값만 기준으로 정렬합니다. 측정기준 또는 측정항목 매개변수에 지정되지 않은 필드를 기준으로 요청이 정렬되면 오류가 발생합니다.
  • 기본적으로 문자열은 en-US 언어에서 알파벳 오름차순으로 정렬됩니다.
  • 숫자는 기본적으로 오름차순으로 정렬됩니다.
  • 날짜는 기본적으로 오름차순으로 정렬됩니다.

필터

filters=ga:medium%3D%3Dreferral
  1. 필터 구문
  2. 필터 연산자
  3. 필터 표현식
  4. 필터 결합
선택사항입니다.

filters 쿼리 문자열 매개변수는 요청에서 반환되는 데이터를 제한합니다. filters 매개변수를 사용하려면 필터링할 측정기준 또는 측정항목과 필터 표현식을 차례로 입력합니다. 예를 들어 다음 쿼리는 뷰 (프로필) 12134에 대해 ga:pageviews 및 ga:browser를 요청합니다. 여기서 ga:browser 측정기준은 Firefox 문자열로 시작합니다.

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

필터링된 쿼리는 결과에 포함되는 행 또는 포함되지 않는 행을 제한합니다. 결과의 각 행은 필터와 대조하여 테스트됩니다. 필터가 일치하면 행이 유지되고 일치하지 않으면 행이 삭제됩니다.

  • URL 인코딩: Google API 클라이언트 라이브러리는 필터 연산자를 자동으로 인코딩합니다.
  • 측정기준 필터링: 필터링은 측정기준이 집계되기 전에 수행되므로 반환된 측정항목은 관련 측정기준에 대한 총계만 나타냅니다. 위의 예에서 페이지 조회수는 Firefox가 브라우저인 페이지 조회수입니다.
  • 측정항목 필터링: 측정항목 필터링은 측정항목이 집계된 후에 실행됩니다.
  • 유효한 조합: 요청의 모든 측정기준/측정항목이 동시에 유효한 조합인 경우 쿼리에 포함되지 않은 측정기준이나 측정항목을 필터링할 수 있습니다. 예를 들어 특정 브라우저를 기준으로 필터링하여 날짜가 지정된 페이지 조회수 목록을 쿼리할 수 있습니다. 자세한 내용은 측정기준 및 측정항목 참조를 참고하세요.

필터 구문


단일 필터는 다음 형식을 사용합니다.

ga:name operator expression

이 구문에서 각 항목은 다음과 같습니다.

  • name - 필터링할 측정기준 또는 측정항목의 이름입니다. 예를 들어 ga:pageviews는 페이지 조회수 측정항목을 필터링합니다.
  • 연산자 - 사용할 필터 일치 유형을 정의합니다. 연산자는 측정기준 또는 측정항목에 따라 달라집니다.
  • 표현식 - 결과에 포함하거나 제외할 값을 지정합니다. 표현식에는 정규 표현식 문법이 사용됩니다.

필터 연산자


측정기준에는 6개의 필터 연산자와 6개의 필터 연산자가 있습니다. 연산자가 URL 쿼리 문자열에 포함되려면 URL로 인코딩되어야 합니다.

팁: Query Explorer는 문자열과 공백이 포함된 URL을 자동으로 인코딩하므로 데이터 피드 쿼리 탐색기를 사용하여 URL 인코딩이 필요한 필터를 설계할 수 있습니다.

측정항목 필터
운영자 설명 URL 인코딩 형식 예
== 같음 %3D%3D 페이지 시간이 정확히 10초인 결과를 반환합니다.
filters=ga:timeOnPage%3D%3D10
!= 같지 않음 !%3D 페이지 시간이 10초가 아닌 결과를 반환합니다.
filters=ga:timeOnPage!%3D10
> 초과 %3E 페이지의 시간이 10초를 초과하는 결과를 반환합니다.
filters=ga:timeOnPage%3E10
< 미만 %3C 페이지의 시간이 10초 미만인 결과를 반환합니다.
filters=ga:timeOnPage%3C10
>= 이상 %3E%3D 페이지 시간이 10초 이상인 결과를 반환합니다.
filters=ga:timeOnPage%3E%3D10
<= 이하 %3C%3D 페이지 시간이 10초 이하인 결과를 반환합니다.
filters=ga:timeOnPage%3C%3D10

측정기준 필터
운영자 설명 URL 인코딩 형식 예
== 일치검색 %3D%3D 도시가 어바인인 측정항목을 집계합니다.
filters=ga:city%3D%3DIrvine
!= 일치하지 않음 !%3D 도시가 어바인이 아닌 측정항목을 집계합니다.
filters=ga:city!%3DIrvine
=@ 하위 문자열 포함 %3D@ 도시에 요크가 포함된 측정항목을 집계합니다.
filters=ga:city%3D@York
!@ 하위 문자열을 포함하지 않음 !@ 도시에 요크가 포함되지 않은 측정항목을 집계합니다.
filters=ga:city!@York
=~ 정규 표현식과 일치하는 항목을 포함합니다. %3D~ 도시가 New로 시작하는 측정항목 집계:
filters=ga:city%3D~%5ENew.*
(%5E는 패턴을 문자열의 시작 부분에 고정하는 ^ 문자에서 인코딩된 URL입니다.)
!~ 정규식과 일치하지 않음 !~ 도시가 New로 시작하지 않는 측정항목 집계:
filters=ga:city!~%5ENew.*

필터 표현식

필터 표현식에는 몇 가지 중요한 규칙이 있습니다.

  • URL 예약 문자 - &와 같은 문자는 일반적인 방식으로 URL 인코딩해야 합니다.
  • 예약 문자 - 세미콜론과 쉼표가 표현식에 나타날 때는 백슬래시로 이스케이프 처리해야 합니다.
    • 세미콜론 \;
    • 쉼표 \,
  • 정규 표현식 - =~ 및 !~ 연산자를 사용하여 필터 표현식에서 정규 표현식을 사용할 수도 있습니다. 구문은 Perl 정규 표현식과 비슷하며 다음과 같은 추가 규칙이 있습니다.
    • 최대 길이 128자(영문 기준) - 128자(영문 기준)가 넘는 정규 표현식을 사용하면 서버에서 400 Bad Request 상태 코드가 반환됩니다.
    • 대소문자 구분: 정규 표현식 일치는 대소문자를 구분하지 않습니다.

필터 결합

OR 및 AND 불리언 로직을 사용하여 필터를 결합할 수 있습니다. 이렇게 하면 필터 표현식의 128자(영문 기준) 글자 제한을 효과적으로 연장할 수 있습니다.

또는

OR 연산자는 쉼표 (,)를 사용하여 정의됩니다. 연산자는 AND 연산자보다 우선하며, 동일한 표현식에서 측정기준과 측정항목을 결합하는 데 사용할 수 없습니다.

예: (각각 URL 인코딩 필요)

국가가 (미국 또는 캐나다)인 경우:
ga:country==United%20States,ga:country==Canada

(Windows 또는 Macintosh) 운영체제의 Firefox 사용자:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

AND

AND 연산자는 세미콜론 (;)을 사용하여 정의됩니다. 앞에 OR 연산자가 옵니다. 이 연산자는 동일한 표현식에서 측정기준과 측정항목을 결합하는 데 사용할 수 있습니다.

예: (각각 URL 인코딩 필요)

국가가 미국이고 브라우저가 Firefox인 경우:
ga:country==United%20States;ga:browser==Firefox

국가가 미국이며 언어가 'en'으로 시작하지 않음:
ga:country==United%20States;ga:language!~^en.*

운영체제가 (Windows 또는 Macintosh)이고 브라우저가 (Firefox 또는 Chrome)인 경우:
ga:operatingSystem==Windows,ga:operatingSystem==Macintosh;ga:browser==Firefox,ga:browser==Chrome

국가가 미국이며 세션이 5회를 초과함:
ga:country==United%20States;ga:sessions>5


세그먼트

segment=gaid::-10
segment=sessions::condition::ga:medium%3D%3Dreferral
segment=users::condition::ga:browser%3D%3DChrome
선택사항입니다.

Core Reporting API에서 세그먼트를 요청하는 방법에 관한 자세한 내용은 세그먼트 개발자 가이드를 참고하세요.

세그먼트의 개념에 대한 개요는 고객센터의 세그먼트 기능 참조 및 세그먼트를 참조하세요.

세그먼트에 허용되는 측정기준 및 측정항목입니다.
일부 측정기준과 측정항목은 세그먼트에서 사용할 수 없습니다. 세그먼트에서 허용되는 측정기준과 측정항목을 검토하려면 측정기준 및 측정항목 탐색기로 이동하세요.

samplingLevel

samplingLevel=DEFAULT
선택사항입니다.
이 매개변수를 사용하여 보고 쿼리의 샘플링 수준 (결과를 계산하는 데 사용되는 세션 수)을 설정합니다. 허용되는 값은 웹 인터페이스와 일치하며 다음을 포함합니다.
  • DEFAULT - 속도와 정확성이 균형을 이루는 샘플 크기로 응답을 반환합니다.
  • FASTER - 샘플 크기가 더 작은 빠른 응답을 반환합니다.
  • HIGHER_PRECISION - 큰 샘플 크기를 사용하여 더 정확한 응답을 반환하지만 이로 인해 응답이 느려질 수 있습니다.
지정하지 않으면 DEFAULT 샘플링 수준이 사용됩니다.
쿼리에 사용된 세션 비율을 계산하는 자세한 방법은 샘플링 섹션을 참조하세요.

빈 행 포함

include-empty-rows=true
선택사항입니다.
기본값은 true입니다. false로 설정하면 모든 측정항목 값이 0인 행이 응답에서 생략됩니다. 예를 들어 쿼리에 측정항목을 2개 이상 포함하면 모든 측정항목 값이 0인 경우에만 행이 삭제됩니다. 이 방법은 유효한 행 수가 예상 측정기준 값의 수보다 훨씬 적을 것으로 예상되는 요청을 실행할 때 유용할 수 있습니다.

start-index

start-index=10
선택사항입니다.
지정하지 않으면 시작 색인은 1입니다. 결과 색인은 1부터 시작합니다. 즉, 첫 번째 행은 0 행이 아니라 1 행입니다. totalResults가 10,000개를 초과하고 10,001개 이상에서 색인이 생성된 행을 검색하려는 경우 이 매개변수를 max-results 매개변수와 함께 페이지로 나누기 메커니즘으로 사용합니다.

max-results

max-results=100
선택사항입니다.
이 응답에 포함할 최대 행 수입니다. 이를 start-index와 함께 사용하여 요소의 하위 집합을 검색하거나, 첫 번째 요소부터 시작하여 반환되는 요소 수를 단독으로 제한할 수 있습니다. max-results가 제공되지 않으면 쿼리는 기본 최대 행 수 1, 000개를 반환합니다.
Analytics Core Reporting API는 요청하는 개수에 관계없이 요청당 최대 10,000개의 행을 반환합니다. 측정기준 세그먼트가 예상한 만큼 많지 않은 경우 요청된 것보다 적은 행이 반환될 수도 있습니다. 예를 들어 ga:country는 가능한 값이 300개 미만이므로 국가별로만 분류할 때는 max-results을 더 높은 값으로 설정하더라도 300개를 초과하는 행을 가져올 수 없습니다.

출력

output=dataTable
선택사항입니다.
이 매개변수를 사용하여 응답에 반환되는 애널리틱스 데이터의 출력 유형을 설정합니다. 허용되는 값은 다음과 같습니다.
  • json - JSON 객체를 포함하는 기본 rows 속성을 응답에 출력합니다.
  • dataTable - 데이터 테이블 객체를 포함하는 dataTable 속성을 응답에 출력합니다. 이 Data Table 객체는 Google 차트 시각화와 함께 직접 사용할 수 있습니다.
지정하지 않으면 기본 JSON 응답이 사용됩니다.

필드

fields=rows,columnHeaders(name,dataType)
선택사항입니다.

부분 응답에서 반환할 필드를 지정합니다. API 응답에서 필드의 하위 집합만 사용하는 경우 fields 매개변수를 사용하여 포함할 필드를 지정할 수 있습니다.

필드 요청 매개변수 값의 형식은 대략 XPath 구문을 기반으로 합니다. 지원되는 구문은 아래에 요약되어 있습니다.

  • 여러 필드를 선택하려면 쉼표로 구분된 목록을 사용합니다.
  • 필드 a 내에 중첩된 필드 b를 선택하려면 a/b를 사용하고, b 내에 중첩된 c 필드를 선택하려면 a/b/c를 사용합니다.
  • 배열 또는 객체의 특정 하위 필드 세트를 요청하려면 하위 선택자를 사용하여 괄호 "( )" 안에 표현식을 넣으세요.
    예를 들어 fields=columnHeaders(name,dataType)는 columnHeaders 배열에서 name 및 dataType 필드만 반환합니다. 단일 하위 필드를 지정할 수도 있으며, 여기서 fields=columnHeader(name)은 fields=columnHeader/name와 같습니다.

prettyPrint

prettyPrint=false
선택사항입니다.

true인 경우 사람이 읽을 수 있는 형식으로 응답을 반환합니다. 기본값: false.

quotaUser

quotaUser=4kh4r2h4
선택사항입니다.

사용자의 IP 주소를 알 수 없는 경우에도 서버 측 애플리케이션에서 사용자별 할당량을 적용할 수 있습니다. 예를 들어 사용자를 대신하여 App Engine에서 크론 작업을 실행하는 애플리케이션이 여기에 해당합니다. 사용자를 고유하게 식별하는 임의의 문자열을 선택할 수 있지만 40자로 제한됩니다.

둘 다 제공되면 userIp가 재정의됩니다.

응답

성공하면 이 요청은 아래에 정의된 JSON 구조로 응답 본문을 반환합니다. 출력 매개변수가 dataTable로 설정되면 요청은 아래에 정의된 JSON (데이터 테이블) 구조로 응답 본문을 반환합니다.

참고: '결과'라는 용어는 쿼리와 일치하는 전체 행 집합을 나타내고 '응답'은 현재 결과 페이지에서 반환된 행 집합을 나타냅니다. itemsPerPage에 설명된 것처럼 총 결과 수가 현재 응답의 페이지 크기보다 큰 경우 결과가 다를 수 있습니다.

JSON
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "include-empty-rows": boolean
    "samplingLevel": string,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "rows": [
    [
      string
    ]
  ],
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

응답 필드

응답 본문 구조의 속성은 다음과 같이 정의됩니다.

속성 이름 값 설명
kind string 리소스 유형입니다. 값은 'analytics#gaData'입니다.
id string 이 데이터 응답의 ID입니다.
query object 이 객체에는 쿼리에 매개변수로 전달된 모든 값이 포함됩니다. 각 필드의 의미는 해당 쿼리 매개변수에 관한 설명에서 확인할 수 있습니다.
query.start-date string 시작일
query.end-date string 종료일
query.ids string 고유한 테이블 ID입니다.
query.dimensions[] list 애널리틱스 측정기준의 목록입니다.
query.metrics[] list 애널리틱스 측정항목 목록입니다.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean 기본값은 true입니다. false로 설정하면 모든 측정항목 값이 0인 행이 응답에서 생략됩니다.
query.sort[] list 데이터가 정렬되는 측정항목 또는 측정기준의 목록입니다.
query.filters string 쉼표로 구분된 측정항목 또는 측정기준 필터 목록입니다.
query.segment string 애널리틱스 세그먼트
query.start-index integer 시작 색인
query.max-results integer 페이지당 최대 결과 수입니다.
startIndex integer start-index 쿼리 매개변수로 지정된 행의 시작 색인입니다. 기본값은 1입니다.
itemsPerPage integer 반환된 실제 행 수와 관계없이 응답에 포함할 수 있는 최대 행 수입니다. max-results 쿼리 매개변수가 지정된 경우 itemsPerPage 값은 max-results과 10,000 중 더 작은 값입니다. itemsPerPage의 기본값은 1,000입니다.
totalResults integer 응답에 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 행 수가 많은 쿼리의 경우 totalResults이 itemsPerPage보다 클 수 있습니다. 대규모 쿼리의 totalResults 및 itemsPerPage에 관한 자세한 설명은 Paging을 참조하세요.
startDate string start-date 매개변수로 지정된 데이터 쿼리의 시작일입니다.
endDate string end-date 매개변수로 지정된 데이터 쿼리의 종료일입니다.
profileInfo object 데이터가 요청된 보기 (프로필)에 대한 정보 조회 (프로필) 데이터는 Google Analytics Management 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 열 유형 'DIMENSION' 또는 'METRIC'입니다.
columnHeaders[].dataType string 데이터 유형. 측정기준 열 헤더의 데이터 유형은 STRING뿐입니다. 측정항목 열 헤더에는 INTEGER, PERCENT, TIME, CURRENCY, FLOAT 등의 측정항목 값에 대한 데이터 유형이 있습니다. 가능한 모든 데이터 유형은 메타데이터 API 응답을 참조하세요.
totalsForAllResults object 측정항목 이름과 값의 키-값 쌍으로 구성된 요청된 측정항목의 총값입니다. 측정항목 총계의 순서는 요청에 지정된 측정항목 순서와 동일합니다.
rows[] list 애널리틱스 데이터 행이며, 각 행에는 측정기준 값 목록과 측정항목 값이 차례로 포함됩니다. 측정기준과 측정항목의 순서는 요청에 지정된 순서와 동일합니다. 각 행에는 N개의 필드 목록이 있습니다. 여기서 N은 측정기준의 수와 측정항목의 수를 합친 값입니다.
JSON (데이터 테이블)
{
  "kind": "analytics#gaData",
  "id": string,
  "selfLink": string,
  "containsSampledData": boolean,
  "query": {
    "start-date": string,
    "end-date": string,
    "ids": string,
    "dimensions": [
      string
    ],
    "metrics": [
      string
    ],
    "samplingLevel": string,
    "include-empty-rows": boolean,
    "sort": [
      string
    ],
    "filters": string,
    "segment": string,
    "start-index": integer,
    "max-results": integer
  },
  "itemsPerPage": integer,
  "totalResults": integer,
  "previousLink": string,
  "nextLink": string,
  "profileInfo": {
    "profileId": string,
    "accountId": string,
    "webPropertyId": string,
    "internalWebPropertyId": string,
    "profileName": string,
    "tableId": string
  },
  "columnHeaders": [
    {
      "name": string,
      "columnType": string,
      "dataType": string
    }
  ],
  "dataTable": {
    "cols": [
      {
        "id": string,
        "label": string,
        "type": string
      }
    ],
    "rows": [
      {
        "c": [
          {    
            "v": string
          }
        ]
      }   
    ]
  },
  "sampleSize": string,
  "sampleSpace": string,
  "totalsForAllResults": [
    {
      metricName: string,
      ...
    }
  ]
}

응답 필드

응답 본문 구조의 속성은 다음과 같이 정의됩니다.

속성 이름 값 설명
kind string 리소스 유형입니다. 값은 'analytics#gaData'입니다.
id string 이 데이터 응답의 ID입니다.
query object 이 객체에는 쿼리에 매개변수로 전달된 모든 값이 포함됩니다. 각 필드의 의미는 해당 쿼리 매개변수에 관한 설명에서 확인할 수 있습니다.
query.start-date string 시작일
query.end-date string 종료일
query.ids string 고유한 테이블 ID입니다.
query.dimensions[] list 애널리틱스 측정기준의 목록입니다.
query.metrics[] list 애널리틱스 측정항목 목록입니다.
query.samplingLevel string Requested sampling level.
query.include-empty-rows boolean 기본값은 true입니다. false로 설정하면 모든 측정항목 값이 0인 행이 응답에서 생략됩니다.
query.sort[] list 데이터가 정렬되는 측정항목 또는 측정기준의 목록입니다.
query.filters string 쉼표로 구분된 측정항목 또는 측정기준 필터 목록입니다.
query.segment string 애널리틱스 세그먼트
query.start-index integer 시작 색인
query.max-results integer 페이지당 최대 결과 수입니다.
startIndex integer start-index 쿼리 매개변수로 지정된 행의 시작 색인입니다. 기본값은 1입니다.
itemsPerPage integer 반환된 실제 행 수와 관계없이 응답에 포함할 수 있는 최대 행 수입니다. max-results 쿼리 매개변수가 지정된 경우 itemsPerPage 값은 max-results과 10,000 중 더 작은 값입니다. itemsPerPage의 기본값은 1,000입니다.
totalResults integer 응답에 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 행 수가 많은 쿼리의 경우 totalResults이 itemsPerPage보다 클 수 있습니다. 대규모 쿼리의 totalResults 및 itemsPerPage에 관한 자세한 설명은 Paging을 참조하세요.
startDate string start-date 매개변수로 지정된 데이터 쿼리의 시작일입니다.
endDate string end-date 매개변수로 지정된 데이터 쿼리의 종료일입니다.
profileInfo object 데이터가 요청된 보기 (프로필)에 대한 정보 조회 (프로필) 데이터는 Google Analytics Management 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 열 유형 'DIMENSION' 또는 'METRIC'입니다.
columnHeaders[].dataType string 데이터 유형. 측정기준 열 헤더의 데이터 유형은 STRING뿐입니다. 측정항목 열 헤더에는 INTEGER, PERCENT, TIME, CURRENCY, FLOAT 등의 측정항목 값에 대한 데이터 유형이 있습니다. 가능한 모든 데이터 유형은 메타데이터 API 응답을 참조하세요.
totalsForAllResults object 측정항목 이름과 값의 키-값 쌍으로 구성된 요청된 측정항목의 총값입니다. 측정항목 총계의 순서는 요청에 지정된 측정항목 순서와 동일합니다.
dataTable object Google 차트와 함께 사용할 수 있는 데이터 표 객체입니다.
dataTable.cols[] list 측정기준에 대한 열 설명어 목록이며 뒤에는 측정항목이 나옵니다. 측정기준과 측정항목의 순서는 metrics 및 dimensions 매개변수를 통해 요청에 지정된 순서와 동일합니다. 열의 수는 측정기준의 수와 측정항목의 수를 합한 값입니다.
dataTable.cols[].id string ID: 열 색인 대신 특정 열을 참조하는 데 사용할 수 있습니다. 측정기준 또는 측정항목 ID는 이 값을 설정하는 데 사용됩니다.
dataTable.cols[].label string 열의 라벨 (시각화로 표시될 수 있음)입니다. 측정기준 또는 측정항목 ID는 이 값을 설정하는 데 사용됩니다.
dataTable.cols[].type string 이 열의 데이터 유형입니다.
dataTable.rows[] list 데이터 표 형식의 애널리틱스 데이터 행이며, 각 행은 측정기준의 셀 값 목록과 측정항목이 차례로 포함된 객체입니다. 측정기준과 측정항목의 순서는 요청에 지정된 순서와 동일합니다. 각 셀에는 N개의 필드 목록이 있습니다. 여기서 N은 측정기준의 수와 측정항목의 수를 합친 값입니다.

오류 코드

요청이 성공하면 Core Reporting API가 200 HTTP 상태 코드를 반환합니다. 쿼리를 처리하는 중에 오류가 발생하면 API에서 오류 코드와 설명을 반환합니다. 분석 API를 사용하는 각 애플리케이션은 적절한 오류 처리 로직을 구현해야 합니다. 오류 코드 및 오류 처리 방법에 대한 자세한 내용은 오류 응답 참조 가이드를 참조하세요.

사용해 보기

Core Reporting API에 쿼리를 사용해 볼 수 있습니다.

  • 쿼리에서 측정항목과 측정기준의 유효한 조합을 보려면 쿼리 탐색기에 매개변수의 샘플 값을 입력하세요. 샘플 쿼리의 결과는 지정된 모든 측정항목 및 측정기준의 값이 포함된 표로 표시됩니다.

  • 실시간 데이터에 대해 요청을 실행하고 JSON 형식으로 응답을 확인하려면 Google Data API 탐색기에서 analytics.data.ga.get 메서드를 사용해 보세요.

샘플링

Google 애널리틱스는 측정기준과 측정항목의 특정 조합을 즉시 계산합니다. Google 애널리틱스에서는 적절한 시간 내에 데이터를 반환하기 위해 데이터 샘플만 처리할 수 있습니다.

samplingLevel 매개변수를 설정하여 요청에 사용할 샘플링 수준을 지정할 수 있습니다.

Core Reporting API 응답에 샘플링된 데이터가 포함되어 있으면 containsSampledData 응답 필드가 true가 됩니다. 또한 두 속성(sampleSize 및 sampleSpace)은 쿼리의 샘플링 수준에 대한 정보를 제공합니다. 이 두 값을 사용하여 쿼리에 사용된 세션의 비율을 계산할 수 있습니다. 예를 들어 sampleSize가 201,000이고 sampleSpace가 220,000이면 보고서는 세션의 (201,000 / 220,000) * 100 = 91.36% 를 기반으로 합니다.

샘플링에 대한 일반적인 설명과 Google 애널리틱스에서 샘플링이 사용되는 방법은 샘플링을 참고하세요.


대규모 데이터 결과 처리

쿼리가 대규모 결과 집합을 반환할 것으로 예상되는 경우, 아래 가이드라인을 사용하여 API 쿼리를 최적화하고, 오류를 방지하고, 할당량 오버런을 최소화하세요. API 요청 하나에 최대 7개의 측정기준과 10개의 측정항목을 허용하여 실적 기준을 설정합니다. 많은 수의 측정항목과 측정기준을 지정하는 일부 쿼리는 다른 쿼리보다 처리 시간이 더 오래 걸릴 수 있지만 요청된 측정항목의 수를 제한하는 것만으로는 쿼리 성능을 향상하기에 충분하지 않을 수 있습니다. 대신 다음 기법을 사용하여 최상의 성능 결과를 얻을 수 있습니다.

쿼리당 측정기준 줄이기

API를 사용하면 요청 하나에 최대 7개의 측정기준을 지정할 수 있습니다. Google 애널리틱스는 이러한 복잡한 쿼리의 결과를 즉시 계산해야 하는 경우가 많습니다. 결과 행 수가 많으면 이 과정에서 특히 시간이 오래 걸릴 수 있습니다. 예를 들어 도시별로 키워드를 쿼리하면 수백만 개의 데이터 행과 일치할 수 있습니다. 쿼리에서 측정기준 수를 제한하여 Google 애널리틱스에서 처리해야 하는 행 수를 줄여 성능을 개선할 수 있습니다.

기간별로 쿼리 분할하기

하나의 긴 기간에 대한 날짜로 입력된 결과를 페이징하는 대신 1주일 또는 하루 동안 한 번에 별도의 쿼리를 만드는 것이 좋습니다. 물론 대규모 데이터 세트의 경우 하루의 데이터를 요청하더라도 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)