引言为什么需要街道级IP定位在很多业务系统中仅知道用户所在城市远远不够。例如本地生活平台需要根据用户所在街道推荐周边商铺或配送范围风控系统需要判断登录IP与常用地址是否在同一个街道级别以识别异常登录广告投放希望将广告定向到特定街道的特定人群。传统的城市级或区县级IP库往往无法满足这些需求。街道级IP查询服务能直接返回街道、门牌等级别的地理信息配合风险评分可以显著提升业务精准度。本文将以一个真实的街道级IP查询API为例完整讲解从接口认知、参数说明到工程化落地的全过程所有示例均基于官方文档中的实际请求与响应。接口能力边界核心能力精确到街道返回street字段街道/乡镇名和street_alternatives备选街道列表覆盖大多数中国大陆IPv4地址。多数据源自动降级主数据源提供街道ISP风险评分risk对象。若主源不可用自动降至备用源城市级ISP响应中的data.source字段标识本次使用的主源primary还是备用源secondary。IPv4与IPv6双栈查询参数ip支持IPv4和IPv6地址不传时自动返回调用方自身IP的定位结果。风险评分risk对象包含代理评分、移动网络占比、综合风险等级等可用于防作弊场景。限制与约束QPS3次/秒共享额度若需更高并发需通过Authorization头携带有效Token。数据覆盖率主源对全球IP覆盖较好但街道级别数据仅在中国大陆及部分国家有较高精度其他地区可能降级到城市级。素材未提供具体覆盖率数字请以集成后的实际回包为准。匿名调用不带Authorization头时受每日调用次数限制限制超出后接口返回错误码。具体额度请查阅官方文档。请求参数与鉴权Query参数参数类型必填说明示例ipstring否待查询的IP地址IPv4或IPv6。不传时自动使用调用方公网IP。110.87.41.14Header参数参数类型必填说明示例Authorizationstring否匿名可用Bearer Token。匿名调用时省略即有调用次数限制超出额度或需要更高QPS时须携带有效Token。Bearer sk_live_xxxxxxxxxxxxxxxx注意文档中同时出现了X-API-Key和Authorization两种鉴权方式实际建议统一使用Authorization: Bearer模式。如果使用X-API-Key则替换Header key。请以官方文档为准。curl接入示例以下提供两个可直接复制的curl示例。为安全起见请将环境变量API_KEY替换为你的真实Token或留空以匿名调用。示例1匿名查询指定IP无需Tokencurl -sS -X GET \ https://v1.apizero.cn/api/ip-pro?ip110.87.41.14示例2带Token查询调用方自身IPexport API_KEYsk_live_xxxxxxxxxxxxxxxx curl -sS -X GET \ -H Authorization: Bearer $API_KEY \ https://v1.apizero.cn/api/ip-pro第二个示例未指定ip参数接口会自动判断请求来源IP。返回结果中data.ip字段即为调用方公网地址。Python代码接入requests适合脚本集成或后端服务调用。以下是一个带超时和异常处理的完整函数import requests import os API_URL https://v1.apizero.cn/api/ip-pro API_KEY os.getenv(API_KEY, ) # 若匿名则留空 def query_ip(ip: str None) - dict: 查询IP地址的地理位置信息。 :param ip: IP地址不传则查调用方自身。 :return: 解析后的JSON响应。 headers {} if API_KEY: headers[Authorization] fBearer {API_KEY} params {} if ip: params[ip] ip try: resp requests.get(API_URL, headersheaders, paramsparams, timeout5) resp.raise_for_status() return resp.json() except requests.exceptions.RequestException as e: print(f请求失败: {e}) raise # 使用示例 result query_ip(117.25.49.203) print(result[data][street]) # 输出城峰镇 print(result[data][risk][level]) # 输出无风险返回值解读成功响应的code字段为0data内包含以下关键字段字段类型说明ipstring查询的IP地址continentstring大洲如亚洲countrystring国家provincestring省份citystring城市districtstring区/县streetstring街道/乡镇主源返回时精确到街道street_alternativesstring[]备选街道地址可能包含多个可能的地名由于IP定位存在一定模糊性此数组提供参考ispstring运营商如电信、联通、移动latitudenumber纬度WGS84longitudenumber经度WGS84area_codestring地区编码如350125city_codestring电话区号如0591zip_codestring邮政编码time_zonestring时区elevationnumber海拔米sourcestring数据来源primary主源含街道或secondary备用源城市级riskobject风险评分对象详见下章risk对象字段字段类型说明scorenumber综合风险评分0–100越高风险越大levelstring风险等级无风险、低风险、中风险、高风险is_proxyboolean是否疑似代理proxy_probabilitynumber代理概率0–100mobile_ratenumber移动网络占比百分比real_ratenumber真实用户占比百分比常见错误与处理1. 参数无效错误码code1001msg参数错误。原因传入的ip格式非法如包含空格、非IP字符串。解决用正则或ipaddress库验证IP格式再传入。2. 鉴权失败错误码code2001msg鉴权失败。原因Token过期、格式错误或者超出匿名额度后未提供Token。解决检查Authorization头是否拼写正确Token是否有效。若为匿名调用且之前正常可能已超日额度需携带Token或等待次日重置。3. QPS超限429 Too Many Requests状态码429。原因请求频率超过3次/秒。解决在客户端实现请求队列或限速或者升级Token提高QPS上限。4. 街道数据不可用现象返回的street字段为空或source为secondary。原因主源对当前IP无街道数据自动降级到备用源。解决业务上需允许降级当source为secondary时使用city或district作为近似地址。工程化注意事项1. 缓存策略精确到街道的IP查询维护复杂度较高建议对同IP短时间内重复查询做缓存。可以使用内存缓存如lru_cache或外部缓存RedisTTL建议设置为5–15分钟因为IP归属地不频繁变动。2. 错误重试与退避网络抖动可能导致偶发失败。建议对5xx和429状态码进行重试采用指数退避例如1s, 2s, 4s。对于4xx参数错误或鉴权失败不重试直接抛异常。3. 降级处理当接口连续失败或返回sourcesecondary时可在业务端使用备用的本地IP库如GeoIP2兜底。务必记录降级日志以便监控。4. 并发控制QPS限制为3请求/秒如果单机有多个服务实例或进程同时调用需要一个全局的速率限制器。可以使用asyncioaiohttp配合aiolimiter或者使用requestsrate-limit装饰器。5. 数据保留合规IP定位结果可能涉及精确位置请遵守所在地区的数据隐私法规如《个人信息保护法》不要将街道级数据长期存储或用于非必要场景。参考文档API官方文档页原始接口文档Markdown
IP地址街道级查询实战：从参数解析到工程化落地
引言为什么需要街道级IP定位在很多业务系统中仅知道用户所在城市远远不够。例如本地生活平台需要根据用户所在街道推荐周边商铺或配送范围风控系统需要判断登录IP与常用地址是否在同一个街道级别以识别异常登录广告投放希望将广告定向到特定街道的特定人群。传统的城市级或区县级IP库往往无法满足这些需求。街道级IP查询服务能直接返回街道、门牌等级别的地理信息配合风险评分可以显著提升业务精准度。本文将以一个真实的街道级IP查询API为例完整讲解从接口认知、参数说明到工程化落地的全过程所有示例均基于官方文档中的实际请求与响应。接口能力边界核心能力精确到街道返回street字段街道/乡镇名和street_alternatives备选街道列表覆盖大多数中国大陆IPv4地址。多数据源自动降级主数据源提供街道ISP风险评分risk对象。若主源不可用自动降至备用源城市级ISP响应中的data.source字段标识本次使用的主源primary还是备用源secondary。IPv4与IPv6双栈查询参数ip支持IPv4和IPv6地址不传时自动返回调用方自身IP的定位结果。风险评分risk对象包含代理评分、移动网络占比、综合风险等级等可用于防作弊场景。限制与约束QPS3次/秒共享额度若需更高并发需通过Authorization头携带有效Token。数据覆盖率主源对全球IP覆盖较好但街道级别数据仅在中国大陆及部分国家有较高精度其他地区可能降级到城市级。素材未提供具体覆盖率数字请以集成后的实际回包为准。匿名调用不带Authorization头时受每日调用次数限制限制超出后接口返回错误码。具体额度请查阅官方文档。请求参数与鉴权Query参数参数类型必填说明示例ipstring否待查询的IP地址IPv4或IPv6。不传时自动使用调用方公网IP。110.87.41.14Header参数参数类型必填说明示例Authorizationstring否匿名可用Bearer Token。匿名调用时省略即有调用次数限制超出额度或需要更高QPS时须携带有效Token。Bearer sk_live_xxxxxxxxxxxxxxxx注意文档中同时出现了X-API-Key和Authorization两种鉴权方式实际建议统一使用Authorization: Bearer模式。如果使用X-API-Key则替换Header key。请以官方文档为准。curl接入示例以下提供两个可直接复制的curl示例。为安全起见请将环境变量API_KEY替换为你的真实Token或留空以匿名调用。示例1匿名查询指定IP无需Tokencurl -sS -X GET \ https://v1.apizero.cn/api/ip-pro?ip110.87.41.14示例2带Token查询调用方自身IPexport API_KEYsk_live_xxxxxxxxxxxxxxxx curl -sS -X GET \ -H Authorization: Bearer $API_KEY \ https://v1.apizero.cn/api/ip-pro第二个示例未指定ip参数接口会自动判断请求来源IP。返回结果中data.ip字段即为调用方公网地址。Python代码接入requests适合脚本集成或后端服务调用。以下是一个带超时和异常处理的完整函数import requests import os API_URL https://v1.apizero.cn/api/ip-pro API_KEY os.getenv(API_KEY, ) # 若匿名则留空 def query_ip(ip: str None) - dict: 查询IP地址的地理位置信息。 :param ip: IP地址不传则查调用方自身。 :return: 解析后的JSON响应。 headers {} if API_KEY: headers[Authorization] fBearer {API_KEY} params {} if ip: params[ip] ip try: resp requests.get(API_URL, headersheaders, paramsparams, timeout5) resp.raise_for_status() return resp.json() except requests.exceptions.RequestException as e: print(f请求失败: {e}) raise # 使用示例 result query_ip(117.25.49.203) print(result[data][street]) # 输出城峰镇 print(result[data][risk][level]) # 输出无风险返回值解读成功响应的code字段为0data内包含以下关键字段字段类型说明ipstring查询的IP地址continentstring大洲如亚洲countrystring国家provincestring省份citystring城市districtstring区/县streetstring街道/乡镇主源返回时精确到街道street_alternativesstring[]备选街道地址可能包含多个可能的地名由于IP定位存在一定模糊性此数组提供参考ispstring运营商如电信、联通、移动latitudenumber纬度WGS84longitudenumber经度WGS84area_codestring地区编码如350125city_codestring电话区号如0591zip_codestring邮政编码time_zonestring时区elevationnumber海拔米sourcestring数据来源primary主源含街道或secondary备用源城市级riskobject风险评分对象详见下章risk对象字段字段类型说明scorenumber综合风险评分0–100越高风险越大levelstring风险等级无风险、低风险、中风险、高风险is_proxyboolean是否疑似代理proxy_probabilitynumber代理概率0–100mobile_ratenumber移动网络占比百分比real_ratenumber真实用户占比百分比常见错误与处理1. 参数无效错误码code1001msg参数错误。原因传入的ip格式非法如包含空格、非IP字符串。解决用正则或ipaddress库验证IP格式再传入。2. 鉴权失败错误码code2001msg鉴权失败。原因Token过期、格式错误或者超出匿名额度后未提供Token。解决检查Authorization头是否拼写正确Token是否有效。若为匿名调用且之前正常可能已超日额度需携带Token或等待次日重置。3. QPS超限429 Too Many Requests状态码429。原因请求频率超过3次/秒。解决在客户端实现请求队列或限速或者升级Token提高QPS上限。4. 街道数据不可用现象返回的street字段为空或source为secondary。原因主源对当前IP无街道数据自动降级到备用源。解决业务上需允许降级当source为secondary时使用city或district作为近似地址。工程化注意事项1. 缓存策略精确到街道的IP查询维护复杂度较高建议对同IP短时间内重复查询做缓存。可以使用内存缓存如lru_cache或外部缓存RedisTTL建议设置为5–15分钟因为IP归属地不频繁变动。2. 错误重试与退避网络抖动可能导致偶发失败。建议对5xx和429状态码进行重试采用指数退避例如1s, 2s, 4s。对于4xx参数错误或鉴权失败不重试直接抛异常。3. 降级处理当接口连续失败或返回sourcesecondary时可在业务端使用备用的本地IP库如GeoIP2兜底。务必记录降级日志以便监控。4. 并发控制QPS限制为3请求/秒如果单机有多个服务实例或进程同时调用需要一个全局的速率限制器。可以使用asyncioaiohttp配合aiolimiter或者使用requestsrate-limit装饰器。5. 数据保留合规IP定位结果可能涉及精确位置请遵守所在地区的数据隐私法规如《个人信息保护法》不要将街道级数据长期存储或用于非必要场景。参考文档API官方文档页原始接口文档Markdown
