Zipcodebase

通过您的 OOMOL 连接账户操作 Zipcodebase。此技能通过 [oo CLI](https://github.com/oomol-lab/oo-cli) 调用 zipcodebase 连接器；OOMOL 在服务端注入凭证，您无需处理原始令牌。

运行操作

假设用户已安装 oo CLI、完成登录并连接了 Zipcodebase。**不要主动运行 oo auth login 或打开连接链接——直接执行操作即可**。仅当命令因认证或连接错误而失败时，才回退至[首次设置](#first-time-setup)。

1. 检查合约，以获取权威的输入/输出模式，再构建请求体：

oo connector schema "zipcodebase" --action "<action_name>"

2. 使用符合输入模式的 JSON 请求体运行操作：

oo connector run "zipcodebase" --action "<action_name>" --data '<json>' --json

• --data 接收一个 JSON 对象字符串或 @path/to/file.json；省略则发送 {}。
• 响应格式为 { "data": ..., "meta": { "executionId": "..." } }；执行 ID 位于 meta.executionId。

每个操作列在下方，附有一行描述；修改状态的操作带有 [write] 或 [destructive] 标签。在构造 --data 前，请使用 oo connector schema 获取操作的实时模式，以确认其输入字段。

可用操作

• calculate_distance — 计算一个邮政编码到一个或多个目标邮政编码之间的距离。
• get_status — 返回 Zipcodebase 账户状态及剩余请求积分。
• list_postal_codes_by_city — 列出与某个城市及可选州/省关联的邮政编码。
• list_postal_codes_by_state — 列出与某个州或省关联的邮政编码。
• list_postal_codes_within_radius — 列出位于某邮政编码半径范围内的邮政编码。
• match_postal_codes_by_distance — 找出提交的邮政编码对中，距离在指定范围内的组合。
• search_postal_codes — 查询一个或多个邮政编码的位置信息。

安全性

• 未标记的操作为读取类（获取 / 列表 / 搜索）——可直接运行。
• **标记为 [write] 的操作会更改 Zipcodebase 状态——运行前请与用户确认具体请求体和影响。**
• **标记为 [destructive] 的操作会删除或覆盖数据——必须确认目标，并获取明确许可后方可执行。**

首次设置

这些是一次性步骤——每次调用无需重复。仅在命令因对应原因失败时才执行相应步骤。

• **oo: command not found** — 安装 oo CLI（其他平台：<https://cli.oomol.com/install-guide.md>）：

  curl -fsSL https://cli.oomol.com/install.sh | bash    # macOS / Linux

  irm https://cli.oomol.com/install.ps1 | iex           # Windows PowerShell

• 未登录 / 认证错误 — 仅需一次登录您的 OOMOL 账户：

  oo auth login

• **scope_missing / credential_expired / app_not_ready / app_not_found** — Zipcodebase 未连接，或连接已过期、缺少权限范围。请一次连接（认证类型：API 密钥）至：

  https://console.oomol.com/app-connections?provider=zipcodebase

• **HTTP 402 / OOMOL_INSUFFICIENT_CREDIT** — 余额不足导致计费中断。请先前往 https://console.oomol.com/billing/token-recharge 充值，再重试。

资源

• Zipcodebase 官方主页：https://zipcodebase.com/