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

适用场景与接口价值IP 地址街道级查询接口能够将 IP 地址解析到街道级别例如“福建省福州市永泰县城峰镇”并结合风险评分、ISP 归属、经纬度等信息。常见的应用场景包括风险控制通过risk字段判断 IP 是否为代理、VPN以及风险等级用于登录、支付等场景的安全校验。内容地理化根据用户 IP 所在省份、城市甚至街道推送本地化内容或限制特定地区访问。用户画像整合 ISP、地区代码、时区等信息辅助分析用户群体分布。内网排查不传ip参数时直接返回调用方自身 IP 的解析结果方便快速定位出口 IP。接口能力边界维度说明请求方法GET请求地址https://v1.apizero.cn/api/ip-proQPS 限制3 次/秒匿名与付费方案共享此限制数据源切换主源提供街道ISP风险评分不可用时自动降级到备用源城市级ISPdata.source标识实际数据源档位IPv6 支持支持参数ip可传入 IPv4 或 IPv6 地址请求参数与鉴权Query 参数参数类型必填说明ipstring否要查询的 IP 地址IPv4 或 IPv6。不传时自动使用调用方自身 IP参数校验注意点传入的 IP 格式必须合法否则返回400 Bad Request。传空字符串或无效 IP如999.999.0.1同样会触发校验错误。传入保留地址如127.0.0.1、10.0.0.1可能返回空或默认值不同服务商处理方式不同建议避免。Header 鉴权参数类型必填说明Authorizationstring否Bearer Token。匿名调用时可省略但受每日配额限制超过配额后必须传入有效 Token鉴权失败场景未携带Authorization且当日匿名配额已用尽 → 返回401 Unauthorized。Authorization格式错误如缺少Bearer前缀→ 返回401 Invalid token。Token 过期或被撤销 → 返回401 Token expired。建议使用环境变量存储 Token避免硬编码export APIZERO_TOKENsk_live_xxxxxxxxxxxxxxxxcurl 请求示例以下示例演示携带 Token 查询指定 IP将$APIZERO_TOKEN替换为实际 Tokencurl -sS \ -X GET \ -H Authorization: Bearer $APIZERO_TOKEN \ https://v1.apizero.cn/api/ip-pro?ip110.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 } }关键字段解释code0 表示成功非 0 表示业务错误见下文常见错误。data.sourceprimary表示主源街道级数据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 secondarystreet字段缺失或为nullrisk可能不完整。原因主源不可用如网络超时、数据更新延迟自动降级到城市级备用源。排错业务上做好降级准备当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_iddef456 ip1.2.3.4 status500 code500 msgInternal error sourcenull降级对外体现如果业务对街道级数据要求严格可在 API 返回sourcesecondary时直接拒绝提供服务或返回明确的错误码给用户避免使用不精确数据引发问题。参考文档IP 地址查询街道级API 文档原始接口说明包含所有字段及错误码