Core Reporting API - 参考指南

本文档提供有关 Core Reporting API 版本 3.0 查询和响应的完整参考。

简介

您可以通过 Core Reporting API 查询 Google Analytics（分析）报告数据。每个查询都必须包含数据视图（配置文件）ID、开始日期和结束日期，以及至少一个指标。您也可以提供更多查询参数（例如，维度、过滤条件和细分）对查询进行细化。请参阅概览指南，了解这些概念如何协同作用。

请求

该 API 提供如下用于请求数据的单一方法：

analytics.data.ga.get()

各种客户端库中均提供此方法，并且此方法针对不同语言提供用于设置查询参数的专用接口。

另外，也可以采用 RESTful 端点的形式查询该 API：

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

每个网址查询参数指定一个 API 查询参数（必须经过网址编码）。

查询参数汇总

下表汇总了 Core reporting API 接受的所有查询参数。点击每个参数名称即可查看详细说明。

名称 值 必需 摘要
ids string 是 ga:XXXX 形式的唯一表格 ID，其中 XXXX 是查询为其检索数据的 Google Analytics（分析）数据视图（配置文件）的 ID。
start-date string 是 获取 Google Analytics（分析）数据的开始日期。请求可以指定格式为 YYYY-MM-DD 的开始日期或相对日期（例如today、yesterday 或 NdaysAgo，其中 N 为正整数）。
end-date string 是 获取 Google Analytics（分析）数据的结束日期。请求可以指定格式为 YYYY-MM-DD 的结束日期，也可以指定相对日期（例如today、yesterday 或 NdaysAgo，其中 N 为正整数）。
metrics string 是 以英文逗号分隔的指标的列表，例如 ga:sessions,ga:bounces。
dimensions string 否 您的 Analytics 数据的一系列以英文逗号分隔的维度，例如 ga:browser,ga:city。
sort string 否 以英文逗号分隔的一系列维度和指标，用于指示所返回数据的排序顺序和排序方向。
filters string 否 限制针对您的请求返回的数据的维度或指标过滤条件。
segment string 否 对您的请求返回的数据进行细分。
samplingLevel string 否 需要的抽样级别。允许的值：
  • DEFAULT — 返回的响应采用默认抽样规模，速度和准确度相平衡。
  • FASTER — 返回的响应采用较小抽样规模，但响应速度更快。
  • HIGHER_PRECISION — 返回的响应采用较大抽样规模，准确度更高，但是响应速度可能较慢。
include-empty-rows boolean 否 默认值为 true；如果设置为 false，将从响应中省略所有指标值为零的行。
start-index integer 否 要检索的第一行数据，从 1 开始。此参数可与 max-results 参数搭配使用，作为分页机制。
max-results integer 否 响应中可包含的行数上限。
output string 否 响应中返回的 Google Analytics（分析）数据所需的输出类型。 可接受的值为 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 回调函数的名称。用于 JavaScript JSON-P 请求。
key string 否 用于在 OAuth 1.0a 授权中指定您的应用，以获取配额。例如：key=AldefliuhSFADSfasdfasdfASdf。

查询参数详情

ids

ids=ga:12345
必填。
用于检索 Analytics（分析）数据的唯一 ID。此 ID 是由命名空间 ga: 与 Google Analytics（分析）数据视图（配置文件）ID 串联而成。您可以使用 analytics.management.profiles.list 方法获取数据视图（配置文件）ID，此方法可在 Google Analytics（分析）Management API 的数据视图（配置文件）资源中提供 id。

start-date

start-date=2009-04-20
必填。
所有 Google Analytics（分析）数据请求都必须指定一个日期范围。 如果您不在请求中添加 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

end-date=2009-05-20
必填。
所有 Google Analytics（分析）数据请求都必须指定一个日期范围。 如果您不在请求中添加 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 会返回每个国家/地区的总网页浏览量。请求指标时，请注意以下事项：
  • 任何请求都必须包含至少一个指标；请求不能完全由维度组成。
  • 对于任何查询，您最多可以提供 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 参数中使用的维度或指标值进行排序。如果您请求按未在 dimensions 或 metrics 参数中指定的字段排序，将会收到错误。
  • 默认情况下，字符串将按 en-US 语言区域的字母顺序升序排序。
  • 默认情况下，数字将按数值顺序升序排序。
  • 默认情况下，日期将按日期顺序升序排序。

filters

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

通过对查询进行过滤，能够对要（或不要）包含在结果中的行加以限制。结果中的每行都要针对过滤条件进行测试：如果满足过滤条件要求，该行会保留下来；如果不能满足过滤条件要求，该行会被丢弃。

  • 网址编码：Google API 客户端库会自动对过滤条件运算符进行编码。
  • 维度过滤：过滤操作发生在对任何维度进行汇总之前，确保返回的指标仅代表相关维度的总和。在上例中，网页浏览量数字将仅统计使用 Firefox 浏览器时的那些网页浏览量。
  • 指标过滤：对指标的过滤操作发生在对指标进行汇总之后。
  • 有效组合：您可以过滤非查询组成部分的维度或指标，条件是请求中的所有维度/指标与过滤条件是有效组合。例如，您可能希望查询已标明日期的网页浏览量列表，并根据特定浏览器进行过滤。有关详情，请参阅维度和指标参考。

过滤条件语法


单个过滤条件使用以下格式：

ga:name operator expression

在这一语法中：

  • name - 过滤所依据的维度或指标的名称。例如：ga:pageviews 会按网页浏览量指标进行过滤。
  • operator - 定义要使用的过滤条件匹配的类型。维度或指标分别有相对应的特定运算符。
  • expression - 说明要包含在结果中或从结果中排除的值。表达式使用正则表达式语法。

过滤条件运算符


维度对应的过滤条件运算符有六种，指标对应的过滤条件运算符也有六种。运算符必须经过网址编码，才能纳入网址查询字符串。

提示：使用数据 Feed 查询浏览器设计需要进行网址编码的过滤条件，因为查询浏览器能够自动对包含字符串和空格的网址进行编码。

指标过滤条件
运算符 说明 网址编码格式 示例
== 等于 %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

维度过滤条件
运算符 说明 网址编码格式 示例
== 完全匹配 %3D%3D 对城市为“Irvine”的指标进行汇总：
filters=ga:city%3D%3DIrvine
!= 不匹配 !%3D 对城市不是“Irvine”的指标进行汇总：
filters=ga:city!%3DIrvine
=@ 包含子字符串 %3D@ 对城市包含“York”的指标进行汇总：
filters=ga:city%3D@York
!@ 不包含子字符串 !@ 对城市不包含“York”的指标进行汇总：
filters=ga:city!@York
=~ 包含与正则表达式匹配的内容 %3D~ 城市以“New”开头的汇总指标：
filters=ga:city%3D~%5ENew.*
（%5E 是 ^ 字符编码的网址，将模式锚定在字符串的开头。）
!~ 不匹配正则表达式 !~ 对城市不以“New”开头的指标进行汇总：
filters=ga:city!~%5ENew.*

过滤条件表达式

下面是过滤条件表达式要遵守的一些重要规则：

  • 网址预留字符 - & 等字符必须以常规方式进行网址编码。
  • 预留字符 - 如果英文分号和英文逗号出现在表达式中，那么必须加上反斜杠进行转义：
    • 分号 \;
    • 逗号 \,
  • 正则表达式 - 您还可以在通过 =~ 和 !~ 运算符过滤表达式中使用正则表达式。其语法类似于 Perl 正则表达式，并且具有以下额外的规则：
    • 最长 128 个字符 - 长度超过 128 个字符的正则表达式会导致从服务器返回 400 Bad Request 状态代码。
    • 区分大小写 - 正则表达式匹配区分大小写。

合并过滤条件

过滤条件可以使用 OR 和 AND 布尔值逻辑进行合并。这样可以有效地扩展过滤条件表达式 128 个字符的限制。

OR

OR 运算符使用英文逗号 (,) 进行定义。该运算符优先于 AND 运算符，并且不能用于在同一表达式中组合维度和指标。

示例：（均须经过网址编码）

国家/地区为“美国”或“加拿大”之一：
ga:country==United%20States,ga:country==Canada

（Windows 或 Macintosh）操作系统上的 Firefox 用户：
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh

以及

AND 运算符使用英文分号 (;) 进行定义。其前面是 OR 运算符，并且可用于在同一表达式中组合维度和指标。

示例：（均须经过网址编码）

国家/地区为美国且浏览器为 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

国家/地区为“United States”并且 (AND) 会话数大于 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

include-empty-rows=true
可选。
默认值为 true；如果设置为 false，将从响应中省略所有指标值为零的行。例如，如果您在查询中加入了多个指标，将仅移除所有指标值均为零的行。当在预期有效行数远少于预期的维度值数量时发出请求时，这样做非常有用。

start-index

start-index=10
可选。
如果未提供，则起始索引为 1。（这样索引将从 1 开始。也就是说，第一行是第 1 行，而不是第 0 行。如果 totalResults 超过 10,000，并且您希望检索索引为 10,001 及以上的行，则可以将此参数与 max-results 参数一起用作分页机制。

max-results

max-results=100
可选。
此响应中包含的行数上限。您可以将此参数与 start-index 结合使用，以检索一部分元素；也可以单独使用此参数，以限制返回的元素数量（从第一个元素开始返回）。 如果未提供 max-results，则查询默认最多返回 1000 行。
无论您请求的数量是多少，Analytics Core Reporting API 针对每个请求最多返回 10,000 行。如果维度细分数量达不到您的预期，API 返回的行数也可能小于请求的数量。例如，如果 ga:country 有不到 300 个可能的值，那么当仅按国家/地区细分时，即使您将 max-results 设为更高的值，所获得的行数也不能超过 300 行。

output

output=dataTable
可选。
使用此参数设置响应中返回的 Google Analytics（分析）数据的输出类型。允许的值包括：
  • json - 在响应中输出默认的 rows 属性，其中包含 JSON 对象。
  • dataTable - 在响应中输出 dataTable 属性，其中包含 数据表对象。此 Data Table 对象可以直接用于 Google 图表可视化图表。
如果未提供此参数，系统将使用默认的 JSON 响应。

字段

fields=rows,columnHeaders(name,dataType)
可选。

指定要在部分响应中返回哪些字段。如果您仅使用 API 响应中的部分字段，则可以使用 fields 参数指定要包含的字段。

fields 请求参数值的格式大致上基于 XPath 语法。支持的语法总结如下。

  • 使用以英文逗号分隔的列表来选择多个字段。
  • 使用 a/b 选择嵌套在字段 a 内的字段 b；使用 a/b/c 选择嵌套在字段 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 引擎上运行定时任务时，会发生此类情况。您可以选择任意字符串用作辨别用户的唯一标识符，但字符数不能超过 40。

如果同时提供两者，这会替换 userIp。

响应

如果成功，此请求返回的响应正文将具有如下定义的 JSON 结构。如果 output 参数设置为 dataTable，则请求返回的响应正文将具有如下定义的 JSON（数据表）结构。

注意：“结果”一词指的是与查询条件相符的所有行，而“响应”指的是当前结果页上返回的所有行。如果结果总数超过当前响应的页面大小，则这些 ID 可能会有所不同（如 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，将从响应中省略所有指标值为零的行。
query.sort[] list 用作数据排序依据的指标或维度列表。
query.filters string 以逗号分隔的指标或维度过滤条件列表。
query.segment string Google Analytics（分析）细分。
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。请参阅 Paging，了解有关用于大型查询的 totalResults 和 itemsPerPage 的更多说明。
startDate string 数据查询的开始日期，由 start-date 参数指定。
endDate string 数据查询的结束日期，由 end-date 参数指定。
profileInfo object 与作为数据请求对象的数据视图（配置文件）的相关信息。数据视图（配置文件）数据可以通过 Google Analytics（分析）管理 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 等。如需了解所有可能的数据类型，请参阅 metadata API 响应。
totalsForAllResults object 以指标名称和值这种键值对的形式，给出所请求指标值的总计。指标总计的顺序与请求中指定的指标顺序相同。
rows[] list Google Analytics（分析）数据行，其中每行都包含一系列维度值和指标值（先维度值后指标值）。维度和指标的顺序与请求中指定的顺序相同。每行都有一个包含 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，将从响应中省略所有指标值为零的行。
query.sort[] list 用作数据排序依据的指标或维度列表。
query.filters string 以逗号分隔的指标或维度过滤条件列表。
query.segment string Google Analytics（分析）细分。
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。请参阅 Paging，了解有关用于大型查询的 totalResults 和 itemsPerPage 的更多说明。
startDate string 数据查询的开始日期，由 start-date 参数指定。
endDate string 数据查询的结束日期，由 end-date 参数指定。
profileInfo object 与作为数据请求对象的数据视图（配置文件）的相关信息。数据视图（配置文件）数据可以通过 Google Analytics（分析）管理 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 等。如需了解所有可能的数据类型，请参阅 metadata 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 采用数据表格式的 Google Analytics（分析）数据行，其中每行都是一个包含一系列维度和指标单元格值（先维度后指标）的对象。维度和指标的顺序与请求中指定的顺序相同。每个单元格都包含 N 个字段的列表，其中 N = 维度数量 + 指标数量。

错误代码

如果请求成功，Core Reporting API 会返回 200 HTTP 状态代码。如果在处理查询期间发生错误，该 API 会返回错误代码和说明。每个使用 Analytics API 的应用都需要实现适当的错误处理逻辑。如需详细了解错误代码及其处理方式，请参阅 错误响应参考指南。

试试看！

您可以尝试一下向 Core Reporting API 发送查询。

  • 要查看查询中的有效指标和维度组合，请在查询浏览器中为参数输入示例值。示例查询的结果以表格形式显示，其中包含所有指定指标和维度的值。

  • 如需对实时数据发出请求并查看 JSON 格式的响应，请尝试 Google Data API Explorer 中的 analytics.data.ga.get 方法。

采样

Google Analytics（分析）需要即时计算维度和指标的特定组合。为了在合理的时间内返回数据，Google Analytics（分析）可能只会处理一部分数据。

您可以通过设置 samplingLevel 参数，为请求指定要使用的抽样级别。

如果 Core Reporting API 响应中包含抽样数据，则 containsSampledData 响应字段将为 true。此外，sampleSize 和 sampleSpace 这两个属性还会提供有关查询的抽样级别信息。利用这两个值，您可以计算用于查询的会话所占的百分比。例如，如果 sampleSize 为 201,000，sampleSpace 为 220,000，则报告的抽样基准是 (201,000 / 220,000) * 100 = 91.36% 的会话。

有关抽样及 Google Analytics（分析）中抽样方法的一般说明，请参阅抽样。


处理大规模的数据结果

如果您预计查询会返回大量结果，请参考以下指南，帮助您优化 API 查询、避免错误以及最大限度减少配额超支情况。请注意，我们设定了性能基准，允许每个 API 请求最多包含 7 个维度和 10 个指标。虽然某些指定大量指标和维度的查询可能比其他查询需要更长的处理时间，但限制所请求指标的数量可能不足以提高查询性能。 不过，您可以使用以下方法获得最佳性能。

减少每个查询中的维度数量

该 API 允许在任何请求中指定最多 7 个维度。 很多时候，Google Analytics（分析）必须实时计算这些复杂查询的结果。如果结果行数很多，这样做可能特别耗时。 例如，按城市（按小时）查询关键字可能会匹配数百万行数据。您可以限制查询中维度的数量，以减少 Google Analytics（分析）处理的行数，从而提高性能。

按日期范围拆分查询

对于日期范围较长的日期键结果，除了分页之外，您还可以考虑仅针对一周甚至一天创建单独查询。当然，对于大型数据集，即使请求一天的数据，返回的数量也可能会超过 max-results，在这种情况下，分页无法避免。但在任何情况下，如果与查询匹配的行数高于 max-results，对日期范围进行拆分可能会缩短获取结果所需的总时间。无论是单线程查询还是并行查询，上述方法都有助于提高性能。

分页

对结果进行分页是将较大的结果集拆分成易管理区块的有效方式。totalResults 字段指示存在多少匹配行，itemsPerPage 则提供结果中可返回的最大行数。如果 totalResults 与 itemsPerPage 的比率较高，则个别查询可能需要更长的时间。如果您只需要有限数量的行（例如，仅用于显示目的），您可能会发现使用 max-results 参数明确限制响应大小会非常方便。不过，如果您的应用需要处理的结果总量非常大，那么，请求行数上限将能提高效率。

使用 gzip

要降低单个请求的带宽需求，您可以选择启用 gzip 压缩，这是一种既方便又简单的方法。虽然这种方法需要一些额外的 CPU 时间对结果进行解压缩，但考虑到它对节约网络费用的贡献，通常还是值得一用的。要接收 gzip 编码的响应，您必须执行以下两项操作：设置 Accept-Encoding 标头，并修改用户代理，使其包含字符串 gzip。 下面提供了一个用于启用 gzip 压缩的格式正确的 HTTP 标头示例：

Accept-Encoding: gzip
User-Agent: my program (gzip)