适用场景IP地理位置查询街道级接口适用于需要精确到街道级别的IP定位场景例如用户行为分析根据IP统计访问者的地理位置分布支持运营决策。本地化内容展示根据用户所在城市或街道提供附近的服务或信息。风险控制结合风险评分字段risk判断IP是否为代理或存在欺诈风险。网络监控与溯源对异常流量进行地域追踪。该接口支持IPv4和IPv6并内置多数据源自动切换与降级机制在保证精度的同时提高了可用性。接口能力边界基本规格项目值接口名称IP 地址查询街道级请求方法GET请求地址https://v1.apizero.cn/api/ip-pro分类地理位置单IP QPS3 / s数据精度街道级主源正常时降级精度城市级主源不可用时QPSQueries 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 参数参数名类型必填说明示例ipstring否要查询的IP地址IPv4或IPv6。不传时自动使用调用方自身IP110.87.41.14不传ip时接口会返回发起请求的客户端公网IP所属地理信息常用于“查我自己”场景。Header 参数参数名类型必填说明Authorizationstring否匿名调用时可省略Bearer Token。匿名调用受每日调用次数限制限制超过调用次数限制或使用付费方案时必须传递有效的 Token匿名调用不传 Authorization的每日调用次数限制是多少素材未明确说明请以官方文档https://apizero.cn/aidocs/ip-pro为准。超过调用次数限制后请求会返回401 Unauthorized 或 403 Forbidden。Token 的获取方式素材也未提及通常需在平台准备后生成。务必保管好 Token不要泄露。curl 接入示例匿名调用查自身IPcurl -sS -X GET https://v1.apizero.cn/api/ip-pro该请求不传递ip参数也不带 Authorization 头每日可使用有限次数。指定IP并携带 Token 调用export MY_API_KEYsk_live_xxxxxxxxxxxxxxxx curl -sS -X GET \ -H Authorization: Bearer ${MY_API_KEY} \ https://v1.apizero.cn/api/ip-pro?ip110.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?ip2001: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 }关键字段说明字段类型说明codeint业务状态码0 表示成功msgstring状态描述request_idstring请求唯一标识可用于追溯日志data.ipstring查询的 IPdata.continentstring大洲名称data.countrystring国家名称data.provincestring省份/州data.citystring城市data.districtstring区县data.streetstring街道/镇主源时存在data.street_alternativesstring[]可能的其他街道名称列表data.ispstring互联网服务提供商data.latitude/data.longitudefloat近似经纬度data.elevationint海拔米data.time_zonestring时区 IANA 标识data.zip_codestring邮编data.area_codestring行政区划代码data.city_codestring电话区号data.riskobject风险评分信息主源时存在data.sourcestring数据源档位primary或backuprisk对象内部字段字段类型说明scoreint风险分数0 表示无风险levelstring风险等级如“无风险”is_proxyboolean是否为代理 IPproxy_probabilityfloat代理概率0-100mobile_ratefloat移动设备请求占比real_ratefloat真实用户占比常见错误与处理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