IP地址查询（街道级）接口调用限制与用量边界详解
适用场景
IP地理位置查询（街道级）接口适用于需要精确到街道级别的IP定位场景，例如：
- 用户行为分析：根据IP统计访问者的地理位置分布，支持运营决策。
- 本地化内容展示：根据用户所在城市或街道，提供附近的服务或信息。
- 风险控制：结合风险评分字段（risk），判断IP是否为代理或存在欺诈风险。
- 网络监控与溯源：对异常流量进行地域追踪。
该接口支持IPv4和IPv6，并内置多数据源自动切换与降级机制，在保证精度的同时提高了可用性。
接口能力边界
基本规格
| 项目 | 值 |
|---|---|
| 接口名称 | IP 地址查询（街道级） |
| 请求方法 | GET |
| 请求地址 | https://v1.apizero.cn/api/ip-pro |
| 分类 | 地理位置 |
| 单IP QPS | 3 / s |
| 数据精度 | 街道级（主源正常时） |
| 降级精度 | 城市级（主源不可用时） |
QPS（Queries Per Second）限制为每秒3次，即每隔约333ms可发起一次请求。若超过此速率，服务端可能返回429 Too Many Requests 或进行限流。开发者需要在自己的应用中实现本地请求排队或节流，避免突发的短时间大量请求导致失败。
数据来源与降级策略
该接口融合了多个数据源：
- 主源：提供街道级信息（street、district）、ISP、风险评分（risk）。响应中
data.source为"primary"。 - 备用源：当主源不可用时自动降级，备用源提供城市级信息（city、province）及ISP，无街道数据。响应中
data.source为"backup"。
降级对调用方透明，无需修改请求参数，但返回字段中street、street_alternatives、risk等可能缺失或为默认值。开发者可通过source字段判断当前数据档位，以决定是否采用结果。
参数与鉴权
Query 参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
ip | string | 否 | 要查询的IP地址（IPv4或IPv6）。不传时自动使用调用方自身IP | 110.87.41.14 |
不传ip时，接口会返回发起请求的客户端公网IP所属地理信息，常用于“查我自己”场景。
Header 参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
Authorization | string | 否（匿名调用时可省略） | Bearer Token。匿名调用受每日调用次数限制限制；超过调用次数限制或使用付费方案时必须传递有效的 Token |
匿名调用（不传 Authorization）的每日调用次数限制是多少？素材未明确说明，请以官方文档（https://apizero.cn/aidocs/ip-pro）为准。超过调用次数限制后，请求会返回401 Unauthorized 或 403 Forbidden。
Token 的获取方式素材也未提及，通常需在平台准备后生成。务必保管好 Token，不要泄露。
curl 接入示例
匿名调用（查自身IP）
curl -sS -X GET "https://v1.apizero.cn/api/ip-pro"该请求不传递ip参数，也不带 Authorization 头，每日可使用有限次数。
指定IP并携带 Token 调用
export MY_API_KEY="sk_live_xxxxxxxxxxxxxxxx" curl -sS -X GET \ -H "Authorization: Bearer ${MY_API_KEY}" \ "https://v1.apizero.cn/api/ip-pro?ip=110.87.41.14"请将MY_API_KEY替换为你自己的有效 Token。若使用环境变量管理密钥，可降低泄露风险。
使用 IPv6 地址查询
curl -sS -X GET \ -H "Authorization: Bearer ${MY_API_KEY}" \ "https://v1.apizero.cn/api/ip-pro?ip=2001:db8::1"返回值解读
成功响应（HTTP 200）返回 JSON 对象，示例（已格式化）：
{ "code": 0, "data": { "area_code": "350125", "city": "福州", "city_code": "0591", "continent": "亚洲", "country": "中国", "country_code": "CN", "district": "永泰", "elevation": 29, "ip": "117.25.49.203", "isp": "电信", "latitude": 25.855039, "longitude": 118.94202, "province": "福建", "risk": { "is_proxy": false, "level": "无风险", "mobile_rate": 4.69, "proxy_probability": 0, "real_rate": 6, "score": 0 }, "source": "primary", "street": "城峰镇", "street_alternatives": [ "福建福州永泰城峰镇", "福建福州永泰大洋镇" ], "time_zone": "Asia/Shanghai", "zip_code": "350000" }, "msg": "成功", "request_id": "abc123" }关键字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，0 表示成功 |
msg | string | 状态描述 |
request_id | string | 请求唯一标识，可用于追溯日志 |
data.ip | string | 查询的 IP |
data.continent | string | 大洲名称 |
data.country | string | 国家名称 |
data.province | string | 省份/州 |
data.city | string | 城市 |
data.district | string | 区县 |
data.street | string | 街道/镇（主源时存在） |
data.street_alternatives | string[] | 可能的其他街道名称列表 |
data.isp | string | 互联网服务提供商 |
data.latitude/data.longitude | float | 近似经纬度 |
data.elevation | int | 海拔（米） |
data.time_zone | string | 时区 IANA 标识 |
data.zip_code | string | 邮编 |
data.area_code | string | 行政区划代码 |
data.city_code | string | 电话区号 |
data.risk | object | 风险评分信息（主源时存在） |
data.source | string | 数据源档位："primary"或"backup" |
risk对象内部字段：
| 字段 | 类型 | 说明 |
|---|---|---|
score | int | 风险分数，0 表示无风险 |
level | string | 风险等级（如“无风险”） |
is_proxy | boolean | 是否为代理 IP |
proxy_probability | float | 代理概率（0-100） |
mobile_rate | float | 移动设备请求占比 |
real_rate | float | 真实用户占比 |
常见错误与处理
| HTTP 状态码 | 错误说明 | 可能原因及处理 |
|---|---|---|
| 400 Bad Request | 请求参数错误 | ip格式非法（如非 IPv4/v6 字符串）。确认参数正确。 |
| 401 Unauthorized | 未提供有效鉴权 | 匿名调用已超出每日限额，或 Token 无效。请检查 Authorization 头格式（必须为 Bearer Token）。 |
| 403 Forbidden | 无权限访问 | Token 已被禁用或 IP 不在白名单（如果平台支持）。 |
| 429 Too Many Requests | 请求频率过高 | 超过 QPS 3/s 限制。应降低请求速率，并实现指数退避重试。 |
| 500 Internal Server Error | 服务端内部错误 | 偶发故障，可稍后重试。若持续出现，需联系技术支持。 |
| 503 Service Unavailable | 服务暂时不可用 | 可能正在维护或所有数据源均不可用。建议退避重试，并监控恢复状态。 |
降级情况下的数据差异
当data.source为"backup"时，下列字段可能缺失或为默认值：
street、street_alternatives：可能为null或空数组。risk：可能为null或默认对象。district：可能缺失（仅到城市级）。
调用方代码应做好字段缺失的容错处理，不应假设所有字段总是存在。
工程化注意事项
1. 请求限频与重试
- 在客户端实现令牌桶或滑动窗口算法，确保每秒请求数不超过 3。
- 遇到 429 错误时，建议采用指数退避（如等待 1s、2s、4s……）重试，最大重试次数根据业务决定（通常 3 次）。
- 对于非致命的 5xx 错误，也可退避重试。
2. 密钥管理
- 绝不在代码中硬编码 Token。使用环境变量或密钥管理服务（如 Vault、AWS Secrets Manager）存储。
3. 数据降级感知
- 检查
data.source字段，配合业务逻辑决定是否接受城市级数据。例如，电商广告投放可能只需要城市级，而物流配送需要街道级。 - 对于需要街道级精度的场景，当
source为"backup"时，可考虑暂时缓存结果并延迟几秒后重试（可能主源恢复），或降级为其他备用 API。
4. 异常监控与报警
- 记录
request_id和响应码，便于排查问题。 - 监控接口错误率（4xx + 5xx）和降级比例，超过阈值时报警。
5. 缓存策略
- IP 地理位置数据相对稳定，可根据业务需求设置合理的缓存 TTL（例如 24 小时），减少重复调用，降低配额消耗。
- 注意：风险评分可能随时间变化，缓存时应考虑是否保留风险字段。
参考文档
- IP 地址查询（街道级）官方文档
- 原始原始文档（Markdown）