Google Ads 数据 API：广告系列、指标与账单

Google Ads（包名 com.google.android.apps.adwords）是 Google 官方推出的安卓客户端，用于在手机上运营 Search、Smart 与 Performance Max 广告系列。用 Google 账号登录后，每个界面都与一套按客户限定范围的数据 API 通信（依据这些功能重建）：账户选择器调用 GET /v1/customers:listAccessible，首页在 POST /v1/customers/{customerId}/campaigns:search 分页广告系列，分析页从 POST /v1/customers/{customerId}/reports/campaignMetrics 读取 impressions、clicks、ctr 与 costMicros。

关键词构建走 POST /v1/customers/{customerId}/keywords:search（text、matchType、qualityScore）。优化卡片来自 GET /v1/customers/{customerId}/recommendations，经 POST /v1/customers/{customerId}/recommendations:apply 应用。账单读取 GET /v1/customers/{customerId}/billingSetups（paymentsAccountId、spendingLimitMicros）；转化跟踪列出 GET /v1/customers/{customerId}/conversionActions 及其 attributionModel。登录后的请求携带从设备 Google 账号签发的 OAuth2 Bearer 令牌。

Google Ads 是 Google 官方推出的安卓客户端，用于在手机上运营 Search、Performance Max、Smart 与展示广告系列：选择客户账户、盯守展示/点击/消耗、编辑关键词、应用优化建议、核对账单并配置转化操作。其数据 API 依据这些界面重建为一套按 customerId 限定范围、需要登录的 REST 接口。账户选择器列出 Google 账号能访问的全部客户；首页返回带 advertisingChannelType、状态与预算的广告系列；分析页分页读取效果指标（impressions、clicks、ctr、costMicros、conversions）；关键词与搜索字词页暴露 matchType 与查询文本；优化建议覆盖提高预算 / 提高出价 / 再分配；账单携带 Google 付款账户 id；转化操作带 attributionModel（数据驱动、末次点击、首次点击、线性、时间衰减、基于位置）。登录后的请求携带从设备 Google 账号签发的 OAuth2 Bearer 令牌。

应用截图

API 端点一览

列出可访问的广告客户
GET /v1/customers:listAccessible opendata
返回登录 Google 账号能打开的全部 Google Ads 客户，填充首页广告系列列表之前的账户选择器。
认证方式：设备上 Google 账号 SSO 签发的 OAuth2 Bearer 访问令牌（Ads 范围）。
- resourceNames
- resourceName
- customerId
- descriptiveName
- currencyCode
- timeZone
- manager
- testAccount
- status
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers:listAccessible HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "resourceNames": [
    "customers/1234567890",
    "customers/9876543210"
  ],
  "customers": [
    {
      "resourceName": "customers/1234567890",
      "customerId": "1234567890",
      "descriptiveName": "Northwind Retail — Brand",
      "currencyCode": "USD",
      "timeZone": "America/New_York",
      "manager": false,
      "testAccount": false,
      "status": "ENABLED"
    }
  ]
}
```
应用内出处
- 依据账户选择器 / 初始加载的 Google 账号 SSO 流程重建
- SSOAuthPlugin 的 fetchTokenForAccount 签发后续请求携带的 Google 账号令牌
读取广告客户账户
GET /v1/customers/{customerId} opendata
加载所选客户的页头信息——名称、币种、时区与优化分数——显示在广告系列列表上方。
认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。
- resourceName
- customerId
- descriptiveName
- currencyCode
- timeZone
- autoTaggingEnabled
- optimizationScore
- status
- trackingUrlTemplate
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers/1234567890 HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "resourceName": "customers/1234567890",
  "customerId": "1234567890",
  "descriptiveName": "Northwind Retail — Brand",
  "currencyCode": "USD",
  "timeZone": "America/New_York",
  "autoTaggingEnabled": true,
  "optimizationScore": 0.82,
  "status": "ENABLED",
  "trackingUrlTemplate": "{lpurl}?utm_source=google&utm_medium=cpc"
}
```
应用内出处
- 依据广告系列首页的账户页头重建
- account_construction 插图是同一客户资源的空账户 / 新建账户状态

搜索广告系列

POST /v1/customers/{customerId}/campaigns:search opendata

分页返回首页广告系列列表，含类型（Search / Smart / Performance Max）、状态、预算与消耗快照。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

campaign
id
name
status
advertisingChannelType
advertisingChannelSubType
biddingStrategyType
campaignBudget
amountMicros
impressions
clicks
costMicros
nextPageToken

依据应用界面重构的示意示例，并非实时抓包。

POST /v1/customers/1234567890/campaigns:search HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Content-Type: application/json

{
  "pageSize": 50,
  "pageToken": "",
  "status": ["ENABLED", "PAUSED"],
  "advertisingChannelType": ["SEARCH", "PERFORMANCE_MAX", "SMART"]
}

{
  "results": [
    {
      "campaign": {
        "resourceName": "customers/1234567890/campaigns/111222333",
        "id": "111222333",
        "name": "Brand — US Search",
        "status": "ENABLED",
        "advertisingChannelType": "SEARCH",
        "advertisingChannelSubType": "SEARCH_MOBILE_APP",
        "biddingStrategyType": "MAXIMIZE_CONVERSIONS",
        "campaignBudget": "customers/1234567890/campaignBudgets/555",
        "amountMicros": "50000000"
      },
      "metrics": {
        "impressions": "58230",
        "clicks": "1987",
        "costMicros": "412100000"
      }
    }
  ],
  "nextPageToken": "CgQItoED"
}

应用内出处

依据广告系列列表首页重建
search_campaign_type、smart_campaign_type 与 uberversal_campaign_type 资源对应 advertisingChannelType 取值

广告系列效果指标

POST /v1/customers/{customerId}/reports/campaignMetrics opendata

读取分析页：单个广告系列按日的展示、点击、CTR、平均 CPC、costMicros 与转化。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

campaignId
currencyCode
date
impressions
clicks
ctr
averageCpc
costMicros
conversions
conversionsValue
allConversions

依据应用界面重构的示意示例，并非实时抓包。

POST /v1/customers/1234567890/reports/campaignMetrics HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Content-Type: application/json

{
  "campaignId": "111222333",
  "dateRange": {"startDate": "2026-09-21", "endDate": "2026-09-27"},
  "segments": ["date"]
}

{
  "campaignId": "111222333",
  "currencyCode": "USD",
  "rows": [
    {
      "date": "2026-09-27",
      "impressions": "9102",
      "clicks": "311",
      "ctr": 0.0342,
      "averageCpc": "2070000",
      "costMicros": "64377000",
      "conversions": 18.5,
      "conversionsValue": 842.10,
      "allConversions": 21.0
    }
  ]
}

应用内出处

依据分析页以及 impressions.png / clicks.png 指标插图重建
feature_promo_card_modify_columns 是该指标表的列选择器

搜索关键词

POST /v1/customers/{customerId}/keywords:search opendata

列出广告系列下的关键词，含匹配类型、质量得分、CPC 出价与消耗——对应关键词构建页。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

criterionId
adGroupId
keyword
text
matchType
status
qualityScore
creativeQualityScore
cpcBidMicros
impressions
clicks
costMicros

依据应用界面重构的示意示例，并非实时抓包。

POST /v1/customers/1234567890/keywords:search HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Content-Type: application/json

{
  "campaignId": "111222333",
  "pageSize": 50,
  "matchType": ["EXACT", "PHRASE", "BROAD"]
}

{
  "results": [
    {
      "criterionId": "3344556677",
      "adGroupId": "888999000",
      "keyword": {"text": "running shoes", "matchType": "EXACT"},
      "status": "ENABLED",
      "qualityInfo": {"qualityScore": 8, "creativeQualityScore": "ABOVE_AVERAGE"},
      "cpcBidMicros": "1500000",
      "metrics": {"impressions": "12040", "clicks": "402", "costMicros": "60300000"}
    }
  ]
}

应用内出处

依据 add-keywords.png 与 feature_promo_card_keyword_construction 重建
match-type.png 对应 keyword.matchType（EXACT / PHRASE / BROAD）

列出优化建议
GET /v1/customers/{customerId}/recommendations opendata
加载优化建议（提高预算、提高/降低出价、再分配），显示在建议标签页。
认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。
- resourceName
- type
- campaignBudgetRecommendation
- currentAmountMicros
- recommendedAmountMicros
- impact
- baseMetrics
- potentialMetrics
- dismissed
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers/1234567890/recommendations?pageSize=20 HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "results": [
    {
      "resourceName": "customers/1234567890/recommendations/rec-raise-budget-01",
      "type": "CAMPAIGN_BUDGET",
      "campaignBudgetRecommendation": {
        "currentAmountMicros": "50000000",
        "recommendedAmountMicros": "75000000"
      },
      "impact": {
        "baseMetrics": {"clicks": 1987, "conversions": 63.0},
        "potentialMetrics": {"clicks": 2610, "conversions": 81.0}
      },
      "dismissed": false
    }
  ]
}
```
应用内出处
- 依据 feature_promo_card_recommendation_intro 与 no-recommendations-to-display 空状态重建
- raise-budget.png、raise-bid.png、lower-bid.png、reallocation.png 与 forecasting_budget_raising.png 对应建议类型

应用优化建议

POST /v1/customers/{customerId}/recommendations:apply opendata

应用一条优化建议（例如提高预算），使变更从手机端落到线上广告系列。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

resourceName
applyParameters
newAmountMicros
applied
campaignBudget
amountMicros

依据应用界面重构的示意示例，并非实时抓包。

POST /v1/customers/1234567890/recommendations:apply HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Content-Type: application/json

{
  "resourceName": "customers/1234567890/recommendations/rec-raise-budget-01",
  "applyParameters": {
    "campaignBudget": {"newAmountMicros": "75000000"}
  }
}

{
  "results": [
    {
      "resourceName": "customers/1234567890/recommendations/rec-raise-budget-01",
      "applied": true,
      "campaignBudget": {
        "resourceName": "customers/1234567890/campaignBudgets/555",
        "amountMicros": "75000000"
      }
    }
  ]
}

应用内出处

依据建议标签页的提高预算 / 提高出价确认流程重建
forecasting_budget_raising.png 是应用前展示的前后影响卡片

读取结算设置
GET /v1/customers/{customerId}/billingSetups openfinance
加载账单页：付款账户、消耗上限与结算设置状态。
认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。账单写入还会打开设备上的 Google 付款账户管理器。
- resourceName
- status
- paymentsAccountId
- paymentsAccountName
- paymentsProfileId
- secondaryPaymentsAccountId
- endTimeType
- spendingLimitMicros
- currencyCode
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers/1234567890/billingSetups HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "results": [
    {
      "resourceName": "customers/1234567890/billingSetups/42",
      "status": "APPROVED",
      "paymentsAccountId": "1234-5678-9012",
      "paymentsAccountName": "Northwind Retail Ads",
      "paymentsProfileId": "1234-5678",
      "secondaryPaymentsAccountId": null,
      "endTimeType": "FOREVER",
      "spendingLimitMicros": "1000000000",
      "currencyCode": "USD"
    }
  ]
}
```
应用内出处
- 依据 feature_promo_card_check_billing 与 payments_gm2_24px 账单图标重建
- PaymentsListener 的 pendingBillingAccountManagerFlowResult / billingAccountManager 打开 Google 付款工具管理器
列出转化操作
GET /v1/customers/{customerId}/conversionActions opendata
列出转化操作及其归因模型（数据驱动、末次点击、首次点击、线性、时间衰减、基于位置），供转化跟踪页使用。
认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。
- resourceName
- id
- name
- status
- type
- category
- countingType
- attributionModel
- defaultValue
- alwaysUseDefaultValue
- primaryForGoal
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers/1234567890/conversionActions HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "results": [
    {
      "resourceName": "customers/1234567890/conversionActions/7001",
      "id": "7001",
      "name": "Purchase",
      "status": "ENABLED",
      "type": "WEBPAGE",
      "category": "PURCHASE",
      "countingType": "ONE_PER_CLICK",
      "attributionModelSettings": {"attributionModel": "GOOGLE_SEARCH_ATTRIBUTION_DATA_DRIVEN"},
      "valueSettings": {"defaultValue": 42.0, "alwaysUseDefaultValue": false},
      "primaryForGoal": true
    }
  ]
}
```
应用内出处
- 依据 conversion_tracking.png、no_conversion_goals.png 与 congrats_screen_conversion 重建
- data-driven / first-click / last-click / linear / time-decay / u-shaped 资源是归因模型选择器

读取更改历史

GET /v1/customers/{customerId}/changeEvents opendata

分页返回更改历史：谁从手机客户端编辑了预算、关键词与广告。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

resourceName
changeDateTime
userEmail
clientType
changeResourceType
changeResourceName
resourceChangeOperation
oldResource
newResource

依据应用界面重构的示意示例，并非实时抓包。

GET /v1/customers/1234567890/changeEvents?pageSize=25 HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json

{
  "results": [
    {
      "resourceName": "customers/1234567890/changeEvents/20260927-184422",
      "changeDateTime": "2026-09-27 18:44:22",
      "userEmail": "[email protected]",
      "clientType": "GOOGLE_ADS_MOBILE_APP",
      "changeResourceType": "CAMPAIGN_BUDGET",
      "changeResourceName": "customers/1234567890/campaignBudgets/555",
      "resourceChangeOperation": "UPDATE",
      "oldResource": {"campaignBudget": {"amountMicros": "50000000"}},
      "newResource": {"campaignBudget": {"amountMicros": "75000000"}}
    }
  ]
}

应用内出处

依据 change_history_empty_state.png（更改历史页的空状态）重建

搜索字词报告
GET /v1/customers/{customerId}/searchTerms opendata
返回搜索字词报告：实际触发广告的查询，含匹配类型与效果。
认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。
- searchTerm
- searchTermMatchType
- status
- campaignId
- adGroupId
- impressions
- clicks
- costMicros
- conversions
依据应用界面重构的示意示例，并非实时抓包。
```
GET /v1/customers/1234567890/searchTerms?campaignId=111222333&pageSize=50 HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Accept: application/json
```
```
{
  "results": [
    {
      "searchTerm": "buy running shoes online",
      "searchTermMatchType": "BROAD",
      "status": "NONE",
      "campaignId": "111222333",
      "adGroupId": "888999000",
      "impressions": "640",
      "clicks": "28",
      "costMicros": "4200000",
      "conversions": 2.0
    }
  ]
}
```
应用内出处
- 依据 search-terms-illustration.svg 与 manage_search_gm2_24px 搜索字词入口重建

创建广告系列

POST /v1/customers/{customerId}/campaigns:create opendata

从应用内创建向导新建 Search、Smart 或 Performance Max 广告系列（从零开始或使用 AI Max / Gemini）。

认证方式：登录 Google 账号的 OAuth2 Bearer 访问令牌（Ads 范围）。

campaign
id
name
status
advertisingChannelType
biddingStrategyType
amountMicros
createWithAi
resourceName

依据应用界面重构的示意示例，并非实时抓包。

POST /v1/customers/1234567890/campaigns:create HTTP/1.1
Authorization: Bearer <google-oauth2-access-token>
Content-Type: application/json

{
  "campaign": {
    "name": "PMax — Fall catalog",
    "status": "PAUSED",
    "advertisingChannelType": "PERFORMANCE_MAX",
    "biddingStrategyType": "MAXIMIZE_CONVERSION_VALUE",
    "amountMicros": "40000000",
    "createWithAi": true
  }
}

{
  "campaign": {
    "resourceName": "customers/1234567890/campaigns/444555666",
    "id": "444555666",
    "name": "PMax — Fall catalog",
    "status": "PAUSED",
    "advertisingChannelType": "PERFORMANCE_MAX",
    "biddingStrategyType": "MAXIMIZE_CONVERSION_VALUE",
    "amountMicros": "40000000"
  }
}

应用内出处

依据 ad-creation.png 以及 create_from_scratch.svg 与 create_with_ai.svg 重建
ai_max_intro.svg 与 gemini_logo.svg 是 AI 辅助创建路径；search/smart/uberversal 广告系列类型资源选择 advertisingChannelType

数据类别

广告客户
广告系列
效果指标
关键词
优化建议
账单
转化
更改历史
搜索字词

数据使用场景与案例

跨渠道消耗看板
代理商 BI 任务从 GET /v1/customers:listAccessible 取出每个客户，再分页调用 POST /v1/customers/{customerId}/reports/campaignMetrics（impressions、clicks、ctr、costMicros、conversions），把 Google 消耗并入与其他付费渠道同一套日级立方。
搜索字词挖掘
关键词运营机器人读取 GET /v1/customers/{customerId}/searchTerms 与 POST /v1/customers/{customerId}/keywords:search（text、matchType、qualityScore），标出仍未做成精确匹配关键词的转化查询。
优化建议自动化
预算节奏服务列出 GET /v1/customers/{customerId}/recommendations，当 impact.potentialMetrics.conversions 越过阈值时，向 POST /v1/customers/{customerId}/recommendations:apply 提交 newAmountMicros——与应用内提高预算卡片同一路径。
账单对账
财务拉取 GET /v1/customers/{customerId}/billingSetups（paymentsAccountId、spendingLimitMicros、currencyCode），把月度发票与核对账单页展示的付款账户对齐。

常见问题

Google Ads 应用使用什么数据 API？

一套需要登录、按客户限定范围的 REST 接口，依据应用界面重建：账户选择器对应 GET /v1/customers:listAccessible，首页列表对应 POST /v1/customers/{customerId}/campaigns:search，分析页对应 POST /v1/customers/{customerId}/reports/campaignMetrics。本页端点是该接口面的示意性映射，而非实时流量记录。

Google Ads 应用如何鉴权？

应用通过设备上的 Google 账号 SSO 登录，并在后续调用中携带带 Ads 范围的 OAuth2 Bearer 访问令牌。不存在匿名浏览——客户、广告系列、关键词与账单读取一律要求该会话。

分析页背后有哪些效果字段？

POST /v1/customers/{customerId}/reports/campaignMetrics 返回 impressions、clicks、ctr、averageCpc、costMicros、conversions、conversionsValue 与 allConversions，可按 date 分段——与应用内指标表和列选择器展示的列一致。

能从应用读取账单与转化配置吗？

可以。GET /v1/customers/{customerId}/billingSetups 返回 paymentsAccountId、paymentsAccountName、spendingLimitMicros 与 currencyCode（对应核对账单页，支付方式编辑走设备上的 Google 付款管理器）。GET /v1/customers/{customerId}/conversionActions 列出转化目标及 attributionModel（数据驱动、末次点击、首次点击、线性、时间衰减、基于位置）。

需要集成这个 App 的数据 API？

我们可为任意指定 App 交付定制集成——源码交付 USD 500 起，或托管 API 按调用计费。告诉我们您需要的数据即可。

每个项目均签 NDA 与 SOW
3–7 天交付
验收通过后才付款
仅在授权范围内作业

获取报价

Google Ads 数据 API：广告系列、指标与账单

应用截图

API 端点一览

列出可访问的广告客户

读取广告客户账户

搜索广告系列

广告系列效果指标

搜索关键词

列出优化建议

应用优化建议

读取结算设置

列出转化操作

读取更改历史

搜索字词报告

创建广告系列

数据类别

数据使用场景与案例

跨渠道消耗看板

搜索字词挖掘

优化建议自动化

账单对账

常见问题

更多企业办公类应用

ADP Mobile Solutions

Meta Ads Manager

Meta Business Suite

MyWalmart

相关主题

需要集成这个 App 的数据 API？

Google Ads 数据 API：广告系列、指标与账单

应用截图

API 端点一览

列出可访问的广告客户

读取广告客户账户

搜索广告系列

广告系列效果指标

搜索关键词

列出优化建议

应用优化建议

读取结算设置

列出转化操作

读取更改历史

搜索字词报告

创建广告系列

数据类别

数据使用场景与案例

跨渠道消耗看板

搜索字词挖掘

优化建议自动化

账单对账

常见问题

相关应用

更多企业办公类应用

ADP Mobile Solutions

Meta Ads Manager

Meta Business Suite

MyWalmart

相关主题

需要集成这个 App 的数据 API？