Core Reporting API - 참조 가이드

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

소개

Google 애널리틱스용 Core Reporting API 보고서 데이터를 쿼리합니다. 각 쿼리에는 보기 (프로필) 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 아니요 응답을 처리하는 자바스크립트 콜백 함수의 이름입니다. 자바스크립트 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=ga:sessions,ga:bounces
필수 항목입니다.
클릭수, 페이지 조회 등 내 사이트 사용자 활동에 대한 집계된 통계입니다. 쿼리에 dimensions 매개변수가 없으면 반환된 측정항목은 요청된 기간 동안 집계 페이지 값(예: 전체 페이지 조회 수 또는 총 이탈 수)을 제공합니다. 측정기준이 요청되면 값은 측정기준 값을 기준으로 분류됩니다. 예를 들어 ga:country로 요청된 ga:pageviews은 국가별 총 페이지 조회수를 반환합니다. 측정항목을 요청할 때는 다음 사항에 주의하세요.
  • 모든 요청은 측정항목을 하나 이상 제공해야 합니다. 요청은 측정기준만으로 구성될 수 없습니다.
  • 쿼리당 최대 10개의 측정항목을 제공할 수 있습니다.
  • 측정기준을 지정하지 않으면 여러 카테고리의 측정항목 조합을 함께 사용할 수 있습니다.
  • 측정항목은 다른 측정기준 또는 측정항목과 함께 사용할 수 있지만, 해당 측정항목에 유효한 조합이 적용되는 경우에만 사용할 수 있습니다. 자세한 내용은 측정기준 및 측정항목 참조를 참고하세요.

sort

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

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

  • 정렬 order는 나열된 측정항목과 측정기준의 왼쪽에서 오른쪽 순서로 지정됩니다.
  • 방향을 정렬하면 기본값이 오름차순으로 설정되며 요청된 필드에 빼기 기호 (-) 프리픽스를 사용해 내림차순으로 변경할 수 있습니다.

쿼리 결과를 정렬하면 데이터에 대해 다른 질문을 할 수 있습니다. 예를 들어 "내 주요 국가는 어디이며, 이러한 브라우저는 어떤 브라우저를 가장 많이 사용하나요? 다음 매개변수를 사용하여 쿼리를 수행할 수 있습니다. 먼저 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

이 구문에서 각 항목의 의미는 다음과 같습니다.

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

필터 연산자


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

도움말: 쿼리 탐색기는 문자열과 공백이 포함된 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
!@ 하위 문자열을 포함하지 않음 !@ 도시에 York가 포함되지 않은 집계 측정항목:
filters=ga:city!@York
=~ 정규 표현식과 일치하는 항목 포함 %3D~ 도시가 신규로 시작하는 측정항목을 집계합니다.
filters=ga:city%3D~%5ENew.*
(%5E는 문자열 시작 부분에 패턴을 고정하는 ^ 문자에서 인코딩된 URL입니다.)
!~ 정규식과 일치하지 않음 !~ 도시가 신규로 시작하지 않는 측정항목을 집계합니다.
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 연산자는 세미콜론(;)을 사용하여 정의됩니다. 연산자 앞에는 OR 연산자가 포함되며 동일한 표현식에 측정기준과 측정항목을 결합하는 데 CAN을 사용할 수 있습니다.

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

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

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

include-empty-rows

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

시작-색인

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

최대 결과

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

출력

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

fields

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

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

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

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

Cute Print

prettyPrint=false
선택사항.

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

할당량 사용자

quotaUser=4kh4r2h4
선택사항.

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

둘 다 제공하는 경우 userIp가 재정의됩니다.

응답

요청이 성공하면 이 요청은 아래에 정의된 JSON 구조를 사용하여 응답 본문을 반환합니다. output 매개변수가 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의 기본값은 1000입니다.
totalResults integer 응답에서 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 다량의 행을 생성하는 쿼리의 경우 totalResults이 itemsPerPage보다 클 수 있습니다. 대규모 쿼리의 경우 totalResults 및 itemsPerPage에 관한 자세한 설명은 Paging을 참고하세요.
startDate string start-date 매개변수로 지정된 데이터 쿼리의 시작일입니다.
endDate string end-date 매개변수로 지정된 데이터 쿼리의 종료일입니다.
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만 포함됩니다. 측정항목 열 헤더에는 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의 기본값은 1000입니다.
totalResults integer 응답에서 반환된 행 수와 관계없이 쿼리 결과의 총 행 수입니다. 다량의 행을 생성하는 쿼리의 경우 totalResults이 itemsPerPage보다 클 수 있습니다. 대규모 쿼리의 경우 totalResults 및 itemsPerPage에 관한 자세한 설명은 Paging을 참고하세요.
startDate string start-date 매개변수로 지정된 데이터 쿼리의 시작일입니다.
endDate string end-date 매개변수로 지정된 데이터 쿼리의 종료일입니다.
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만 포함됩니다. 측정항목 열 헤더에는 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 애널리틱스는 적절한 시간 내에 데이터를 반환하기 위해 데이터 샘플만 처리할 수 있습니다.

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

Core 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)