Google Analytics Data API 概览

您可以使用 Data API 以编程方式访问 Google Analytics 报告数据。

详细了解 Google Analytics 媒体资源。

API 返回的数据与 Google Analytics 界面中显示的数据一致，并且完全遵循为 Google Analytics 媒体资源配置的在报告中使用的 ID 设置（例如“混合”“观测”或“基于设备”）。

以下是您可以使用 Google Analytics Data API v1 生成报告的一些示例：

  • 您的 Android 应用上周的日活跃用户数。
  • 过去 28 天内，您网站上排名前 10 的网页获得的网页浏览量。
  • 过去 30 分钟内，您的 iOS 应用在每个国家/地区有多少活跃用户。

您还可以使用 Google Analytics Data API v1 执行以下操作：

  • 构建自定义信息中心，以展示 Google Analytics 数据。
  • 自动完成复杂的报告任务，从而节约时间。
  • 将 Google Analytics 数据与其他业务应用集成。

数据一致性和在报告中使用的 ID

Google Analytics Data API v1 访问的报告数据与 Google Analytics 界面访问的报告数据相同。API 返回的数据完全遵循为 Google Analytics 媒体资源配置的在报告中使用的 ID 设置，因此用户数、去重和数据建模会与媒体资源设置中选择的身份空间（例如“混合”“实测”或“基于设备”）保持一致。

如需详细了解不同的身份空间对报告的影响，请参阅在报告中使用的 ID。

开始使用

如需开始使用 Java、Python、Node.js、PHP、C#、Go 或 Ruby 客户端库，请参阅客户端库快速入门。如需了解如何构建查询、过滤维度和读取响应，请参阅创建报告，或在查询浏览器中以交互方式测试查询。

runReport 请求和响应示例

如需通过 REST 查询事件数据，请向 runReport 端点发送 POST 请求，并在 RunReportRequest JSON 正文中指定 dateRanges、dimensions 和 metrics：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [
    { "startDate": "7daysAgo", "endDate": "yesterday" }
  ],
  "dimensions": [
    { "name": "country" }
  ],
  "metrics": [
    { "name": "activeUsers" }
  ]
}

或者，使用应用默认凭证运行等效的 curl 命令：

curl -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [
      { "startDate": "7daysAgo", "endDate": "yesterday" }
    ],
    "dimensions": [
      { "name": "country" }
    ],
    "metrics": [
      { "name": "activeUsers" }
    ]
  }'

API 会返回一个包含列标题和数据行的 RunReportResponse：

{
  "dimensionHeaders": [
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "activeUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "United States" }],
      "metricValues": [{ "value": "4820" }]
    },
    {
      "dimensionValues": [{ "value": "Japan" }],
      "metricValues": [{ "value": "2541" }]
    }
  ],
  "rowCount": 2,
  "kind": "analyticsData#runReport"
}

可用方法

以下是 Data API 方法列表。如需了解详情，请参阅参考文档。

  • runReport 此方法会返回 Google Analytics 事件数据的自定义报告，是简单报告查询的首选方法。
  • batchRunReports：这是 runReport 方法的批量版本，可让您使用单个 API 调用生成多个报告。
  • runPivotReport 此方法会返回您的 Google Analytics 事件数据的自定义透视报告。透视报告比常规报告更高级，表现形式也更丰富。每个透视表都描述了报告响应中可见的维度列和行。
  • batchRunPivotReports 这是 runPivotReport 方法的批量版本，可让您通过一次 API 调用生成多份报告。
  • getMetadata 此方法会返回报告方法中可用的维度和指标的元数据。用于探索维度和指标。此方法的响应还包括可用于指定 Google Analytics 媒体资源的自定义维度和指标。
  • checkCompatibility 此方法会列出可添加到报告请求中并保持兼容性的维度和指标。
  • runRealtimeReport 此方法会返回媒体资源的自定义实时事件数据报告。事件在发送到 Google Analytics 几秒钟后就会显示在实时报告中。实时报告会显示从当前时刻到 30 分钟前（对于 Google Analytics 360 版媒体资源，最长可达 60 分钟）这段时间范围内的事件和使用情况数据。
  • properties.audienceExports 一组方法，可让您生成受众群体导出，其中包含受众群体中用户的快照。
  • properties.recurringAudienceLists （早期预览版）一组可让您管理周期性受众群体导出的方法。周期性受众群体导出每天都会生成新的受众群体名单。
  • runFunnelReport （早期预览版）此方法会返回您的 Google Analytics 事件数据的自定义漏斗报告。借助漏斗探索，您可以直观了解用户为完成任务而采取的步骤，并能迅速查看用户在每个步骤的表现。
  • properties.chat （早期预览版）此方法提供对 Google Analytics 中的 Ask Advisor 的程序化对话式访问。您可以使用自然语言询问有关事件数据的问题、诊断性能变化，并获得结构化叙述和表格形式的数据洞见。

支持的维度和指标

如需查看 Data API 支持的所有维度和指标的列表，请参阅 API 架构文档。