IP 地址街道级查询接口排错全解：参数、鉴权与数据降级

适用场景与接口价值

IP 地址街道级查询接口能够将 IP 地址解析到街道级别（例如"福建省福州市永泰县城峰镇"），并结合风险评分、ISP 归属、经纬度等信息。常见的应用场景包括：

• 风险控制 ：通过 risk 字段判断 IP 是否为代理、VPN，以及风险等级，用于登录、支付等场景的安全校验。
• 内容地理化：根据用户 IP 所在省份、城市甚至街道，推送本地化内容或限制特定地区访问。
• 用户画像：整合 ISP、地区代码、时区等信息，辅助分析用户群体分布。
• 内网排查 ：不传 ip 参数时直接返回调用方自身 IP 的解析结果，方便快速定位出口 IP。

接口能力边界

维度	说明
请求方法	GET
请求地址	https://v1.apizero.cn/api/ip-pro
QPS 限制	3 次/秒（匿名与付费方案共享此限制）
数据源切换	主源提供街道+ISP+风险评分，不可用时自动降级到备用源（城市级+ISP）；data.source 标识实际数据源档位
IPv6 支持	支持，参数 ip 可传入 IPv4 或 IPv6 地址

请求参数与鉴权

Query 参数

参数	类型	必填	说明
ip	string	否	要查询的 IP 地址（IPv4 或 IPv6）。不传时自动使用调用方自身 IP

参数校验注意点：

• 传入的 IP 格式必须合法，否则返回 400 Bad Request。
• 传空字符串或无效 IP（如 999.999.0.1）同样会触发校验错误。
• 传入保留地址（如 127.0.0.1、10.0.0.1）可能返回空或默认值，不同服务商处理方式不同，建议避免。

Header 鉴权

参数	类型	必填	说明
Authorization	string	否	Bearer Token。匿名调用时可省略，但受每日配额限制；超过配额后必须传入有效 Token

鉴权失败场景：

• 未携带 Authorization 且当日匿名配额已用尽 → 返回 401 Unauthorized。
• Authorization 格式错误（如缺少 Bearer 前缀）→ 返回 401 Invalid token。
• Token 过期或被撤销 → 返回 401 Token expired。

建议使用环境变量存储 Token，避免硬编码：

export APIZERO_TOKEN="sk_live_xxxxxxxxxxxxxxxx"

curl 请求示例

以下示例演示携带 Token 查询指定 IP（将 $APIZERO_TOKEN 替换为实际 Token）：

curl -sS \
  -X GET \
  -H "Authorization: Bearer $APIZERO_TOKEN" \
  "https://v1.apizero.cn/api/ip-pro?ip=110.87.41.14"

若只需查询自身 IP（匿名）：

curl -sS -X GET "https://v1.apizero.cn/api/ip-pro"

返回字段解读

成功时 HTTP 状态码为 200，返回 JSON 结构如下：

{
  "code": 0,
  "msg": "成功",
  "request_id": "abc123",
  "data": {
    "ip": "117.25.49.203",
    "continent": "亚洲",
    "country": "中国",
    "country_code": "CN",
    "province": "福建",
    "city": "福州",
    "city_code": "0591",
    "district": "永泰",
    "street": "城峰镇",
    "street_alternatives": ["福建福州永泰城峰镇", "福建福州永泰大洋镇"],
    "area_code": "350125",
    "zip_code": "350000",
    "time_zone": "Asia/Shanghai",
    "elevation": 29,
    "latitude": 25.855039,
    "longitude": 118.94202,
    "isp": "电信",
    "risk": {
      "score": 0,
      "level": "无风险",
      "is_proxy": false,
      "proxy_probability": 0,
      "real_rate": 6,
      "mobile_rate": 4.69
    },
    "source": "primary"
  }
}

关键字段解释

• code：0 表示成功，非 0 表示业务错误（见下文常见错误）。
• data.source ："primary" 表示主源街道级数据，"secondary" 表示降级到备用源（城市级，无 street 字段）。
• data.street：街道名称，仅在主源可用时有值；若为空或缺失，说明该 IP 无街道级数据或已降级。
• data.street_alternatives：备选街道列表，用于地址补全或模糊匹配。
• data.risk ：风险评分对象，score 为 0--100 整数，等级可参考 level 字段（如"无风险""低风险""高风险"）。is_proxy 标识是否为代理。

常见错误与排错方法

1. 400 Bad Request -- 参数错误

症状 ：返回 {"code": 400, "msg": "Invalid IP format"} 或类似。

原因：

• ip 参数不是合法的 IPv4 或 IPv6 地址。
• ip 参数包含非法字符（如空格、中文）。

排错：

• 使用正则或库校验 IP 格式后再传入。
• 注意 URL 编码（空格应编码为 %20 或直接移除）。
• 若查询自身 IP，不传 ip 参数即可。

2. 401 Unauthorized -- 鉴权失败

症状 ：{"code": 401, "msg": "Authentication required"} 或 "Invalid token"。

原因：

• 匿名调用当日配额已用尽。
• 未传入 Authorization 头。
• Token 格式有误（如缺少 Bearer 或 token 字符串包含空格）。
• Token 已过期或已被撤销。

排错：

• 检查当日调用次数，若超过匿名限制，必须携带有效 Token。
• 确认 Token 前缀为 sk_live_ 且无尾随换行。
• 在代码中避免拼接多余字符："Bearer " + token.trim()。

3. 429 Too Many Requests -- QPS 超限

症状 ：{"code": 429, "msg": "Rate limit exceeded"}。

原因：每秒请求数超过 3 次。

排错：

• 在客户端引入限流（例如令牌桶、滑动窗口）。
• 对同一 IP 的重复查询添加缓存，减少请求量。
• 若需要高频查询，联系服务商申请更高 QPS 或使用分布式限流协调。

4. 500 或 502 -- 服务端异常

症状 ：HTTP 500、502，或返回 {"code": 500, "msg": "Internal error"}。

原因：

• 主源和备用源同时不可用（概率极低）。
• 网络抖动导致请求超时。

排错：

• 实现指数退避重试（建议最多 3 次，间隔 1s、2s、4s）。
• 仅对 5xx 重试，对 4xx 不重试。
• 记录 request_id 便于向服务商反馈问题。

5. 数据降级 -- source 为 secondary

症状 ：data.source = "secondary"，street 字段缺失或为 null，risk 可能不完整。

原因：主源不可用（如网络超时、数据更新延迟），自动降级到城市级备用源。

排错：

• 业务上做好降级准备：当 source 不为 "primary" 时，输出精度降低的提示或使用 district、city 等字段作为后备。
• 监控 source 字段，触发告警以便人工介入。
• 降级通常为临时状态，可稍后重试恢复主源。

6. 街道数据缺失 -- 即使 source 为 primary 也可能无 street

原因：部分 IP（如数据中心、移动基站地址）可能无法解析到街道级。

排错：

• 判断 data.street 是否存在，不存在则回退到 district 或 city。
• 不要假设所有 IP 都能返回街道数据。

7. 编码与数据类型问题

中文乱码 ：确认程序读响应时使用 UTF-8 解码。 浮点数精度 ：latitude、longitude 为双精度浮点，使用高精度类型存储。

工程化注意事项

缓存策略

• 对于同一 IP 的查询结果，建议本地缓存 5--10 分钟（因 IP 归属变化不频繁）。
• 缓存键为 IP 字符串，值为 data 对象，注意 source 字段变更时需刷新。

限流与重试

• 客户端安装一个令牌桶，1 秒产生 3 个 Token，防止触发 429。
• 重试时区分错误类型：
  • 5xx：重试（最多 3 次）。
  • 429：等待 1 秒后重试（若依然 429，则缓存失败结果并稍后重试）。

错误处理日志

记录 request_id、ip、HTTP 状态码、code、msg 和 source，便于排查。例如：

ERROR ip_query_failed request_id=def456 ip=1.2.3.4 status=500 code=500 msg="Internal error" source=null

降级对外体现

如果业务对街道级数据要求严格，可在 API 返回 source=secondary 时直接拒绝提供服务或返回明确的错误码给用户，避免使用不精确数据引发问题。

参考文档

• IP 地址查询（街道级）API 文档
• 原始接口说明（包含所有字段及错误码）