如何通过Google Ads REST API获取美国按州名汇总的地域报告

原有调用逻辑的核心问题 #

• GAQL语法不符合Google Ads API规范，字段名、资源名、筛选值写法错误，用字符串'USA'做国家筛选存在匹配误差，是返回结果混入非美国数据的核心原因
• 选错了报告查询资源，没有指定地域粒度为州级，也没有拉取州名称字段，导致无法按州名维度做数据汇总

正确调用规则 #

• 使用专门存储地域粒度效果数据的geographic_view作为查询主资源
• 用美国固定地域准则ID2840做国家筛选，完全避免字符串匹配带来的非美国数据混入问题
• 增加地域类型筛选geographic_view.location_type = 'STATE'，强制只返回州级粒度数据，排除国家、城市、商圈等其他层级的结果
• 显式拉取geo_target_constant.name字段，直接拿到标准州名，无需额外通过州ID做映射转换
• 日期参数格式统一为'YYYY-MM-DD'加单引号，支持自定义替换起止日期
• 效果指标使用API规定的标准字段名，比如花费对应metrics.cost_micros，不要使用不存在的自定义字段名

可直接使用的curl调用代码 #

# 替换<START_DATE>和<END_DATE>为需要的查询起止日期，格式为YYYY-MM-DD即可
curl "https://googleads.googleapis.com/v10/customers/${CUSTOMER_ID}/googleAds:searchStream" \
  --header "Content-Type: application/json" \
  --header "developer-token: ${DEVELOPER_TOKEN}" \
  --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
  --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
  --data '{
    "query": "
      SELECT
        geo_target_constant.name,
        segments.date,
        metrics.cost_micros,
        metrics.impressions,
        metrics.clicks,
        metrics.conversions
      FROM geographic_view
      WHERE
        geographic_view.country_criterion_id = 2840
        AND geographic_view.location_type = '\''STATE'\''
        AND segments.date BETWEEN '\''<START_DATE>'\'' AND '\''<END_DATE>'\''
    "
  }'

返回结果中geo_target_constant.name即为美国各州标准名称，所有返回条目均为美国州级效果数据，如果需要补充其他效果指标，直接在SELECT段中增加对应metrics前缀的指标字段即可。

内容的提问来源于stack exchange，提问作者Code Guy