本文档提供有关 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 |
否 | 您的 Google Analytics(分析)数据的一系列以英文逗号分隔的维度,例如 ga:browser,ga:city 。
|
sort |
string |
否 | 以英文逗号分隔的一系列维度和指标,用于指示返回数据的排序顺序和排序方向。 |
filters |
string |
否 | 维度或指标过滤条件,用于限制您的请求返回的数据。 |
segment |
string |
否 | 对您的请求返回的数据进行细分。 |
samplingLevel |
string |
否 | 需要的抽样级别。允许使用的值:
|
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
ga:
与 Google Analytics(分析)数据视图(配置文件)ID 结合而成。您可以使用 analytics.management.profiles.list
方法提取数据视图(配置文件)ID,此方法能够提供 Google Analytics(分析)Management API 数据视图(配置文件)资源中的 id
。start-date
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
。start-date 没有上限限制。以下示例使用相对日期表示过去 7 天的日期范围(从昨天开始向前追溯):
&start-date=7daysAgo &end-date=yesterday
end-date
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:pageviews
并使用了 ga:country
,则系统将返回按国家/地区细分的网页浏览总量。请求指标时,请注意以下事项:- 任何请求都必须包含至少一个指标;请求不能完全由维度组成。
- 对于任何查询,您最多可以提供 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
参数时,请注意以下事项:
- 只能按在
dimensions
或metrics
参数中使用的维度值或指标值进行排序。如果您请求按未在 dimensions 或 metrics 参数中指定的字段排序,将会收到错误。 - 默认情况下,字符串将按 en-US 语言区域的字母顺序升序排序。
- 默认情况下,数字将按数值顺序升序排序。
- 默认情况下,日期将按日期顺序升序排序。
filters
filters=ga:medium%3D%3Dreferral
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
会依据 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 |
!@ |
不包含子字符串 | !@ |
对“city”不包含“York”的指标进行汇总:filters=ga:city!@York |
=~ |
包含与正则表达式匹配的内容 | %3D~ |
对“city”以“New”开头的指标进行汇总:filters=ga:city%3D~%5ENew.* (%5E 是 ^ 字符的网址编码格式,将字符串的开头部分限定为某一格式。) |
!~ |
与正则表达式不匹配 | !~ |
对“city”不以“New”开头的指标进行汇总:filters=ga:city!~%5ENew.* |
过滤条件表达式
下面是过滤条件表达式要遵守的一些重要规则:
- 网址预留字符 -
&
等字符必须以常规方式进行网址编码。 - 预留字符 - 如果英文分号和英文逗号出现在表达式中,那么必须加上反斜杠进行转义。
- 英文分号
\;
- 英文逗号
\,
- 英文分号
- 正则表达式 - 您还可以在过滤条件表达式中使用正则表达式,即使用
=~
和!~
运算符。其语法类似于 Perl 正则表达式,不过有如下额外规则:- 最长 128 个字符 - 如果正则表达式长度超过 128 个字符,服务器会返回
400 Bad Request
状态代码。 - 区分大小写 - 正则表达式匹配区分大小写。
- 最长 128 个字符 - 如果正则表达式长度超过 128 个字符,服务器会返回
合并过滤条件
过滤条件可以使用 OR
和 AND
布尔值逻辑进行合并。这样可以有效地扩展过滤条件表达式 128 个字符的限制。
OR
OR
运算符使用英文逗号 (,
) 进行定义。它的运算优先级高于 AND
运算符,并且在同一个表达式中不能用于组合维度和指标。
示例:(均须经过网址编码)
国家/地区为(“United States”或 [OR]“Canada”):
ga:country==United%20States,ga:country==Canada
(“Windows”或 [OR]“Macintosh”)操作系统上的 Firefox 用户:
ga:browser==Firefox;ga:operatingSystem==Windows,ga:operatingSystem==Macintosh
AND
AND
运算符使用英文分号 (;
) 进行定义。它的运算优先级低于 OR
,并且在同一个表达式中可以组合维度和指标。
示例:(均须经过网址编码)
国家地区为“United States”并且 (AND) 浏览器为 Firefox:
ga:country==United%20States;ga:browser==Firefox
国家/地区为“United States”并且 (AND) 语言不以“en”开头:
ga:country==United%20States;ga:language!~^en.*
操作系统为(“Windows”或 [OR]“Macintosh”),并且 (AND) 浏览器为(“Firefox”或 [OR]“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
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
start-index
start-index=10
1
。(这样索引将从 1 开始。也就是说,第一行的索引是 1
,而不是 0
。)如果 totalResults
超过 10000,并且您希望提取索引为 10001 以及更后面的行,可以将此参数与 max-results
参数搭配,作为分页机制使用。max-results
max-results=100
start-index
搭配使用,以提取一部分元素;也可以单独使用此参数,以限制返回的元素数(从第一个元素开始返回)。如果未提供 max-results
,则默认情况下,查询最大返回 1000 行。ga:country
维度,可能的值不足 300,那么当按国家/地区细分时,您能得到的结果将不会超过 300 行,即使您将 max-results
设为超过 300 的值仍是如此。output
output=dataTable
json
- 在响应中输出默认的rows
属性,其中包含一个 JSON 对象。dataTable
- 在响应中输出dataTable
属性,其中包含一个数据表对象。此Data Table
对象可以直接用于 Google 图表可视化内容。
fields
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。
如果 quotaUser 与 userIp
同时提供,quotaUser 会覆盖 userIp。
响应
如果成功,此请求返回的响应正文将具有如下定义的 JSON 结构。如果 output 参数设为 dataTable
,则请求返回的响应正文将具有如下定义的 JSON(数据表)结构。
注意:“结果”一词指的是与查询条件相符的所有行,而“响应”指的是当前结果页上返回的所有行。当结果总数大于当前响应页面可显示的结果数上限时(如 itemsPerPage 中所述),这两个词代表的结果数会有所不同。
{
"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 。请参阅分页,了解当查询返回的结果非常多时,有关使用 totalResults 和 itemsPerPage 的更多说明。
|
startDate |
string |
日期查询的开始日期,由 start-date 参数指定。 |
endDate |
string |
日期查询的结束日期,由 end-date 参数指定。 |
selfLink |
string |
指向此数据查询结果页的链接。 |
previousLink |
string |
指向此数据查询前一结果页的链接。 |
nextLink |
string |
指向此数据下一查询结果页的链接。 |
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 = 维度数量 + 指标数量。 |
{
"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 。请参阅分页,了解当查询返回的结果非常多时,有关使用 totalResults 和 itemsPerPage 的更多说明。
|
startDate |
string |
日期查询的开始日期,由 start-date 参数指定。 |
endDate |
string |
日期查询的结束日期,由 end-date 参数指定。 |
selfLink |
string |
指向此数据查询结果页的链接。 |
previousLink |
string |
指向此数据查询前一结果页的链接。 |
nextLink |
string |
指向此数据下一查询结果页的链接。 |
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 会返回错误代码和相关说明。使用 Google 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)