Google Analytics Data API 概览

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

详细了解 Google Analytics 媒体资源。

API 返回的数据与 Google Analytics 界面中显示的数据一致，并且完全遵循为您的 Google Analytics 媒体资源配置的 在报告中使用的 ID 设置（例如混合型、观察型或基于设备的 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，请参阅 在报告中使用的 ID。

开始使用

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

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 架构文档。