SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场standardize-geo-values

standardize-geo-values

办公与效率

查看项目

更新于 10-16 04:37

技能介绍

用途

该技能解决 HubSpot 中地理字段格式不统一的问题。当联系人和公司记录里的「国家/地区」与「州/地区」存在多种写法时（如 US、USA、U.S. 与 United States，NY 与 New York），按「United States」创建的列表会漏掉被标记为 US 或 USA 的联系人，导致基于地区的营销活动和地理报表出现受众规模不准、联系人遗漏。该技能用于把所有联系人与公司记录中的地理值转换为单一标准格式。

主要能力

技能围绕三个阶段脚本展开：

  • 标准化前审计（before.py）：按每个变体值统计联系人和公司的数量，建立基线。其核心查询模式为对 contacts 和 companies 对象，遍历 variants = ["US", "USA", "U.S.", "U.S.A.", "America"]，使用搜索 API 按 country 属性精确匹配统计总数。
  • 执行标准化（execute.py）：应用变体到标准值的映射表，通过批量更新写入 HubSpot。脚本内置 COUNTRY_MAPPING 与 STATE_MAPPING 两张映射表示例（如 "US": "United States"、"UK": "United Kingdom"、"NY": "New York"、"CA": "California" 等），并注明需先审阅和按审计结果扩展这些表。执行流程为：搜索含变体值的记录 → 分页收集匹配记录 ID（通过 after 游标）→ 批量更新（每次 100 条）→ 对联系人和公司分别重复。
  • 标准化后验证（after.py）：重新检查各变体，确认联系人和公司均返回 0。

脚本运行方式：

  • uv run skills/standardize-geo-values/scripts/before.py
  • uv run skills/standardize-geo-values/scripts/execute.py
  • uv run skills/standardize-geo-values/scripts/after.py

同时提供不依赖脚本的手动方案：在 HubSpot UI 中为每个变体创建静态列表、批量编辑字段；或在 Companies 视图中以相同方式处理公司。

使用方式

技能定义了前置条件：需先完成第一阶段的数据清理（先移除无效/已删除联系人）；需要 HubSpot 私有应用访问令牌，以 HUBSPOT_ACCESS_TOKEN 写入 .env，并具备联系人和公司的读写权限范围；需要 Python 3.10+ 与 uv；需要在 Contacts 和 Companies 视图中有批量编辑权限。

执行前需与用户确认两项信息：

  1. 国家值偏好格式（全称如 United States、ISO 两字母如 US、ISO 三字母如 USA），默认全称，与 HubSpot 默认表单行为一致。
  2. 是否存在 Salesforce 或其他 CRM 集成要求特定格式，默认无集成约束，使用全称格式。

标准格式的推荐值：国家使用全称（如 United States、United Kingdom）；联系人层级的州使用全称（如 New York、California）。

执行计划：审计所有非标准国家与州值（before 状态）→ 构建变体到标准值的映射表 → 通过 API 脚本或 HubSpot UI 手动批量编辑 → 通过配置属性类型和表单防止未来不一致 → 验证所有值已标准化（after 状态）。

防复发措施：进入设置 > 属性 > 联系人属性，检查 Country/Region 是否为下拉选择字段而非自由文本；对 State/Region 做同样检查（州可能因跨多个国家而不适合下拉）；检查所有活跃表单（Marketing > Forms）中的国家和州字段是否为下拉且选项值与标准格式一致；检查团队使用的导入模板是否引用标准值。

适用场景

适用于运行区域定向活动或按地理维度出报表的 B2B 企业，需要保证地理细分的可靠性；也适用于刚完成数据清理、准备修正历史遗留格式问题的 HubSpot 管理员。

限制

  • 需要具备相应权限的 HubSpot 私有应用令牌与 Python 环境。
  • 若 CRM 与 Salesforce 等系统集成，必须在标准化前与该系统管理员就标准格式达成一致，否则会导致持续的同步冲突。
  • 不应处理空白或空值。本流程只标准化已存在但非标准的值，补全缺失国家数据属于单独的丰富化任务。
  • 公司层级的州缩写可能被接受。HubSpot 对公司 State/Region 的默认行为常使用缩写，需自行决定是否标准化公司州字段。
  • 搜索 API 每次查询上限为 10,000 条结果，必要时需分段。
  • 批量更新每次最多接受 100 条记录，限流为每 10 秒 100 次请求。
  • 批量编辑上限因套餐而异，HubSpot 可能限制每次批量编辑的规模（100–250 条），大量数据可能需重复操作或改用 API。
  • 回滚依赖 execute 脚本的 CSV 审计轨迹（记录每条被修改记录及其原值），可据此批量改回原值；个别值也可从每条记录的属性历史中还原。
  • 建议在批量编辑前导出受影响的联系人和公司当前值作为备份 CSV。

技术要点

  • 根因治理与清理同样重要：变体通常由导入、API 集成或绕过下拉的自由文本表单字段产生，需修复表单、导入模板与集成映射。
  • 映射表需根据自身审计结果审阅和扩展，脚本内仅提供部分示例，包括需按需补充全部 50 个美国州及领地。