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 的开始日期,也可以指定相对日期(例如,todayyesterdayNdaysAgo,其中 N 是正整数)。
end-date string 获取 Google Analytics(分析)数据的结束日期。请求可以指定格式为 YYYY-MM-DD 的结束日期,也可以指定相对日期(例如,todayyesterdayNdaysAgo,其中 N 是正整数)。
metrics string 以英文逗号分隔的指标列表,例如 ga:sessions,ga:bounces
dimensions string 您的 Google 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(分析)数据所需的输出类型。 可接受的值为 jsondataTable。默认值: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
必需。
所有 Analytics(分析)数据请求都必须指定日期范围。 如果您未在请求中添加 start-dateend-date 参数,服务器会返回一个错误。日期值可以是使用 YYYY-MM-DD 模式的特定日期,也可以是使用 todayyesterdayNdaysAgo 模式的相对值。值必须与 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 一致。
最早的 start-date2005-01-01。 开始日期没有上限限制。
相对日期始终与查询时的当前日期相关,并且基于查询中指定的数据视图(配置文件)的时区。

以下示例使用相对日期表示过去 7 天的日期范围(从昨天开始向前追溯):

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

end-date

end-date=2009-05-20
必需。
所有 Analytics(分析)数据请求都必须指定日期范围。 如果您未在请求中添加 start-dateend-date 参数,服务器会返回一个错误。日期值可以是使用 YYYY-MM-DD 模式的特定日期,也可以是使用 todayyesterdayNdaysAgo 模式的相对值。值必须与 [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo) 一致。
最早的 end-date2005-01-01end-date 没有上限限制。
相对日期始终与查询时的当前日期相关,并且基于查询中指定的数据视图(配置文件)的时区。

以下示例使用相对日期表示过去 10 天的日期范围(从今天开始向前追溯):

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

dimensions

dimensions=ga:browser,ga:city
可选。
dimensions 参数会按常用条件(例如 ga:browserga: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
可选。

用于指示返回数据的排序顺序和排序方向的一系列指标和维度。

  • 排序顺序由所列指标和维度按从左到右的顺序指定。
  • 排序方向默认为升序。您可以通过为所请求的字段添加减号 (-) 前缀将排序方向改为降序。

通过对查询结果排序,您可以解决许多数据方面的疑问。例如,为了解决“哪些国家/地区的用户最多,他们最常使用哪些浏览器”这一问题,您可以使用以下参数进行查询。查询结果首先按 ga:country 排序,然后按 ga:browser 排序,并且这两个指标均按升序排序:

sort=ga:country,ga:browser

要回答相关问题,“我的热门浏览器有哪些?哪些国家/地区的用户最常使用这些浏览器,您可以使用以下参数进行查询。查询结果首先按 ga:browser 排序,然后按 ga:country 排序,并且这两个指标均按升序排序:
sort=ga:browser,ga:country

使用 sort 参数时,请注意以下几点:

  • 只能按您在 dimensionsmetrics 参数中使用的维度值或指标值进行排序。如果您请求按未在 dimensions 或 metrics 参数中指定的字段排序,将会收到错误。
  • 默认情况下,字符串将按 en-US 语言区域的字母顺序升序排序。
  • 默认情况下,数字将按数值顺序升序排序。
  • 默认情况下,日期将按日期顺序升序排序。

filters

filters=ga:medium%3D%3Dreferral
可选。

filters 查询字符串参数会限制请求返回的数据。如需使用 filters 参数,请提供要用作过滤依据的维度或指标,然后紧接着提供过滤条件表达式。例如,以下查询针对数据视图(配置文件)12134 请求 ga:pageviewsga: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 “城市”不是“欧文”的汇总指标:
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 状态代码。
    • 区分大小写 - 正则表达式匹配区分大小写。

合并过滤条件

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

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 OR Macintosh) 且浏览器为 (Firefox OR 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

include-empty-rows=true
可选。
默认为 true;如果设置为 false,响应中所有指标值均为零的行将被忽略。例如,如果您在查询中加入了多个指标,将仅移除所有指标值均为零的行。在发出请求时,预计有效行数会远远小于预期维度值数,这非常有用。

start-index

start-index=10
可选。
如果未提供,起始索引为 1。(这样索引将从 1 开始。也就是说,第一行是第 1 行,而不是第 0 行。)当 totalResults 超过 10000 且您希望检索索引为 10001 及以上的行时,可将此参数与 max-results 参数搭配使用,以作为分页机制。

max-results

max-results=100
可选。
此响应中可包含的行数上限。您可以将此参数与 start-index 结合使用,以检索一部分元素;也可以单独使用此参数,以限制返回的元素数(从第一个元素开始返回)。如果未提供 max-results,则查询会返回默认最多 1000 行的数据。
Google Analytics(分析)Core Reporting API 每次请求最多返回 10000 行,无论您请求的数量是多少。如果维度细分数量达不到您的预期,API 返回的行数也可能小于请求的数量。例如,ga:country 的可能值少于 300,因此如果仅按国家/地区进行细分,即使您将 max-results 设为更高的值,也不能超过 300 行。

输出

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

fields

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

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

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

  • 使用以英文逗号分隔的列表来选择多个字段。
  • 使用 a/b 选择嵌套在字段 a 内的字段 b;使用 a/b/c 来选择嵌套在字段 b 中的字段 c。
  • 通过将表达式放在括号 "( )" 中,使用子选择器请求数组或对象的一组特定子字段。
    例如:fields=columnHeaders(name,dataType) 仅返回 columnHeaders 数组中的 namedataType 字段。 您还可以指定单个子字段,其中 fields=columnHeader(name) 等同于 fields=columnHeader/name

prettyPrint

prettyPrint=false
可选。

如果 true,系统会以用户可读的格式返回响应。 默认值:false


quotaUser

quotaUser=4kh4r2h4
可选。

利用此参数,即使您不知道用户的 IP 地址,也可以通过服务器端的应用,强制执行每个用户的配额限制。例如,当应用代表用户在 App 引擎上运行定时任务时,会发生此类情况。您可以选择任意字符串用作辨别用户的唯一标识符,但字符数不能超过 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,将从响应中省略所有指标值为零的行。
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 或 10000 中的较小者。itemsPerPage 的默认值为 1000。
totalResults integer 查询结果中的总行数,与响应中返回的行数无关。对于导致大量行的查询,totalResults 可以大于 itemsPerPage。如需查看有关大型查询的 totalResultsitemsPerPage 的更多说明,请参阅分页
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 列标题,其中列出维度名称和指标名称(先维度名称后指标名称)。维度和指标的顺序与请求中通过 metricsdimensions 参数指定的维度和指标的顺序相同。标头数量等于维度数量与指标数量之和。
columnHeaders[].name string 维度或指标的名称。
columnHeaders[].columnType string 列类型。值为“DIMENSION”或“METRIC”。
columnHeaders[].dataType string 数据类型。维度列标头只有 STRING 这一种数据类型。指标列标头指明指标值的数据类型,例如 INTEGERPERCENTTIMECURRENCYFLOAT 等。如需了解所有可能的数据类型,请参阅 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 或 10000 中的较小者。itemsPerPage 的默认值为 1000。
totalResults integer 查询结果中的总行数,与响应中返回的行数无关。对于导致大量行的查询,totalResults 可以大于 itemsPerPage。如需查看有关大型查询的 totalResultsitemsPerPage 的更多说明,请参阅分页
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 列标题,其中列出维度名称和指标名称(先维度名称后指标名称)。维度和指标的顺序与请求中通过 metricsdimensions 参数指定的维度和指标的顺序相同。标头数量等于维度数量与指标数量之和。
columnHeaders[].name string 维度或指标的名称。
columnHeaders[].columnType string 列类型。值为“DIMENSION”或“METRIC”。
columnHeaders[].dataType string 数据类型。维度列标头只有 STRING 这一种数据类型。指标列标头指明指标值的数据类型,例如 INTEGERPERCENTTIMECURRENCYFLOAT 等。如需了解所有可能的数据类型,请参阅 Metadata API 响应
totalsForAllResults object 以指标名称和值这种键值对的形式,给出所请求指标值的总计。指标总计的顺序与请求中指定的指标顺序相同。
dataTable object 可以直接用于 Google 图表可视化内容数据表对象。
dataTable.cols[] list 维度和指标(先维度后指标)的列描述符列表。维度和指标的顺序与请求中通过 metricsdimensions 参数指定的维度和指标的顺序相同。列数量等于维度数量与指标数量之和。
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。此外,以下 2 个属性还会提供查询的抽样级别相关信息:sampleSizesampleSpace。 使用这两个值,您可以计算用于查询的会话所占的百分比。例如,如果 sampleSize201,000,而 sampleSpace220,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 规定结果中可返回的行数上限。如果 totalResultsitemsPerPage 的比率较高,则各个查询所需的时间可能比必要时间要长。如果您只需要有限数量的行(例如用于显示目的),您可能会发现通过 max-results 参数设置明确的响应大小限制非常方便。不过,如果您的应用需要处理的结果总量非常大,那么,请求行数上限将能提高效率。

使用 gzip

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

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