2023년 7월 1일부터 표준 유니버설 애널리틱스 (UA) 속성의 데이터 처리가 중단되었습니다. 2024년 7월 1일부터 UA 360 속성의 데이터 처리가 중단되며, Google 애널리틱스 4로 이전됨에 따라 일부 UA 360 기능이 그전에 지원 중단됩니다. Data API를 사용하여 GA4 속성의 보고 기능에 액세스합니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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입니다. true로 설정하면 모든 측정항목 값이 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

필수 항목입니다.

가장 빠른 유효한 end-date는 2005-01-01입니다. end-date의 상한선은 없습니다.

상대적 날짜는 항상 쿼리 시점의 현재 날짜를 기준으로 하며 쿼리에 지정된 뷰 (프로필)의 시간대를 기준으로 합니다.

상대 날짜를 사용한 지난 10일 (오늘 시작) 기간의 예는 다음과 같습니다.

  &start-date=9daysAgo
  &end-date=today

측정기준

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는 국가별 총 페이지 조회수를 반환합니다. 측정항목을 요청할 때는 다음 사항에 유의하세요.

모든 요청은 측정항목을 하나 이상 제공해야 합니다. 요청은 측정기준으로만 구성될 수 없습니다.
모든 쿼리에 최대 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

필터 구문
필터 연산자
필터 표현식
필터 결합
- OR 연산자
- AND 연산자

선택사항입니다.

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는 페이지 조회수 측정항목을 필터링합니다.
operator — 사용할 필터링 일치 유형을 정의합니다. 연산자는 측정기준 또는 측정항목에 따라 달라집니다.
표현식 - 결과에 포함하거나 제외할 값을 지정합니다. 표현식은 정규 표현식 문법을 사용합니다.

필터 연산자

측정기준에는 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`
`!@`	하위 문자열을 포함하지 않음	`!@`	도시에 요크가 포함되지 않은 측정항목을 집계합니다. `filters=ga:city!@York`
`=~`	정규 표현식과 일치하는 항목을 포함합니다.	`%3D~`	도시가 New로 시작하는 측정항목을 집계합니다. `filters=ga:city%3D~%5ENew.*` (%5E는 패턴을 문자열의 시작 부분에 고정하는 ^ 문자에서 인코딩된 URL입니다.)
`!~`	정규식과 일치하지 않음	`!~`	도시가 신규로 시작하지 않는 측정항목을 집계합니다. `filters=ga:city!~%5ENew.*`

필터 표현식

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

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

필터 결합

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

OR

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

국가가 미국이며 언어가 '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에서 세그먼트를 요청하는 방법에 관한 자세한 내용은 세그먼트 개발자 가이드를 참고하세요.

세그먼트의 개념은 고객센터의 세그먼트 기능 참조 및 세그먼트를 확인하세요.

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

참고: dynamic:: 프리픽스는 2014년 3월 27일부로 지원 중단되었습니다. 가능한 한 빨리 새로운 구문으로 마이그레이션하는 것이 좋습니다.

samplingLevel

samplingLevel=DEFAULT

선택사항입니다.

이 매개변수를 사용하여 보고 쿼리의 샘플링 수준 (즉, 결과를 계산하는 데 사용되는 세션 수)을 설정합니다. 허용되는 값은 웹 인터페이스와 일치하며 다음을 포함합니다.

DEFAULT - 속도와 정확성이 균형을 이루는 샘플 크기와 함께 응답을 반환합니다.
FASTER - 더 작은 샘플 크기로 빠른 응답을 반환합니다.
HIGHER_PRECISION - 큰 샘플 크기를 사용하여 더 정확한 응답을 반환하지만 이로 인해 응답이 느려질 수 있습니다.

지정하지 않으면 DEFAULT 샘플링 수준이 사용됩니다.

쿼리에 사용된 세션의 비율을 계산하는 방법에 관한 자세한 내용은 샘플링 섹션을 참고하세요.

include-empty-rows

include-empty-rows=true

선택사항입니다.

기본값은 true입니다. true로 설정하면 모든 측정항목 값이 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입니다. true로 설정하면 모든 측정항목 값이 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` 매개변수에 지정된 데이터 쿼리의 종료일입니다.
`selfLink`	`string`	이 데이터 쿼리에 대한 결과 페이지의 링크
`previousLink`	`string`	이 데이터 쿼리에 대한 이전 결과 페이지 링크입니다.
`nextLink`	`string`	이 데이터 쿼리에 대한 결과의 다음 페이지 링크
`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`	응답에 샘플링된 데이터가 포함되어 있으면 참입니다.
`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입니다. true로 설정하면 모든 측정항목 값이 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` 매개변수에 지정된 데이터 쿼리의 종료일입니다.
`selfLink`	`string`	이 데이터 쿼리에 대한 결과 페이지의 링크
`previousLink`	`string`	이 데이터 쿼리에 대한 이전 결과 페이지 링크입니다.
`nextLink`	`string`	이 데이터 쿼리에 대한 결과의 다음 페이지 링크
`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`	응답에 샘플링된 데이터가 포함되어 있으면 참입니다.
`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 쿼리를 최적화하고, 오류를 방지하고, 할당량 초과를 최소화하세요. Google에서는 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)