提取实验的地理位置数据

如需自动或大规模拉取 GeoX 实验的数据，您必须使用 Google Ads API 拉取费用和支出数据。然后，您需要将这些数据与内部 CRM、销售终端 (POS) 或内部销售数据库中的原始、未经过滤且未归因的转化或收入数据相结合。

推荐的 Recommender API 工作流架构

如需按地理位置细分准确拉取广告系列和费用数据，请遵循以下架构：

• 服务 ：使用 GoogleAdsService，具体来说是 Search 或 SearchStream 方法。

• 资源 ：查询 geographic_view 以了解用户实际所处的地理位置或感兴趣的地理位置，这通常是 GeoX 实验的标准。或者，查询 location_view以根据 广告系列定位的特定地理位置查看效果。

  注意 ：请勿使用 campaign_location_target_report，因为此旧版 AdWords API 报告已停用。

• 要包含的字段 ：

  • campaign.id
  • segments.date
  • segments.geo_target_city （或区域或国家/地区，具体取决于 GeoX 的粒度）
  • metrics.cost_micros

• GAQL 查询示例 ：对于 GeoX，广告客户使用 Google Ads API 拉取费用指标，而不是归因转化（应来自内部 CRM 或第三方系统）。您可以使用以下查询：

  SELECT
    campaign.id,
    segments.date,
    segments.geo_target_city,
    metrics.cost_micros
  FROM geographic_view
  WHERE segments.date DURING LAST_30_DAYS
  

  注意： geographic_view 仅针对在给定日期记录了展示或支出的地理位置细分返回行。如需在 GeoX 时序中包含支出为零的天数和区域，请在数据流水线中针对日期和目标区域的完整笛卡尔积执行左外联接。

注意 ：如果您从 Google Ads 拉取转化指标，则拉取的是“归因” 转化，也就是说，您只会看到 Google 算法 已归因的销售额。强烈建议您不要在 GeoX 中使用归因数据，因为归因逻辑会使因果衡量产生偏差。

后处理和数据提取

• 地理位置细分映射 ：API 不会在报告数据视图中返回纯文本名称（例如“New York”）或短代码（例如“501”或“ES”）。`segments.geo_target_city`segments.geo_target_city 或 `segments.geo_target_country`segments.geo_target_country 等字段会返回指向 `GeoTargetConstantGeoTargetConstant` 的资源名称字符串（例如 `geoTargetConstants/1023191geoTargetConstants/1023191`）。提取数字 ID (`10231911023191`) 并查询 `geo_target_constant`geo_target_constant 资源：

  SELECT
    geo_target_constant.id,
    geo_target_constant.name,
    geo_target_constant.canonical_name
  FROM geo_target_constant
  WHERE geo_target_constant.id = 1023191
  

  或者，如需在代码中本地执行联接，请在地理位置定位目标处下载静态地理位置定位目标 CSV。

• 费用转化 ：API 以微美元为单位返回费用值。您必须将 metrics.cost_micros 除以 1,000,000，才能输出上传文件中所需的标准货币值。

用于定位突变的地理位置 ID

在执行广告系列或广告组地理位置定位突变时，广告客户必须查找并传递所选区域的确切 GeoTargetConstant ID (geoTargetConstants/ID)。您无法传递原始 ISO 或 Nielsen 代码。

区域类型	必需的 API ID (GeoTargetConstant)	旧有格式（请勿使用）
DMA 区域	ID 200501（适用于纽约）	Nielsen 代码（例如，501 适用于纽约）
国家/地区	ID 2724（适用于西班牙）	ISO 代码（例如，"ES" 适用于西班牙）

最佳实践和常见格式错误

• 日期格式 ：segments.date 字段以 YYYY-MM-DD 格式返回 ISO-8601 日期字符串。在 ETL 流水线中，将日期字段明确序列化为 YYYY-MM-DD 字符串，并避免在会自动重新设置日期列格式的电子表格应用中打开导出的 CSV 文件。
• 邮政编码中的前导零 ：在整个数据流水线中，将邮政编码和 ZIP 代码（例如 01234）视为字符串类型（VARCHAR 或 STRING），而不是整数，这样就不会去除前导零。
• 汇总 ：如果进行多单元格研究，您必须为每个处理组提供单独的支出指标。
• 联接转化数据 ：与内部 CRM 系统或内部销售数据库中的转化数据联接时，请确保转化数据具有以下属性，以确保与 Google Ads API 数据和 GeoX 进行无缝数据处理：
  • 每日时序 ：数据必须按天汇总。
  • 地理位置级别 ：每个转化都必须映射到您正在测试的确切地理位置单位（例如，将客户的送货邮政编码与设计中使用的 DMA 或邮政编码集群进行匹配）。
  • 总值 ：数据必须是非负的绝对值，例如总收入或总转化次数。如果您的 CRM 跟踪的是净收入（退款为负值），则必须使用实验的总数，并在稍后应用退款比率。