适用场景与调用压力特征身份证归属地查询接口接收身份证号前 6 位区划代码返回省、市、区三级行政区划信息。这类能力通常出现在以下三类业务中表单地址自动回填用户在准备或实名认证页面输入身份证号后前端先调用接口补全省市区减少手动输入。数据治理与清洗存量用户表中只有身份证号、缺失地域字段时需要批量反查归属地并落库。风控策略辅助运营或风控系统将归属地与 IP 属地、收货地址做交叉比对用于异常行为识别。三类场景的请求特征差异很大。表单回填多为稀疏请求峰值集中在业务高峰时段批量清洗则是连续密集请求容易在短时间内打满接口的 QPS 上限。理解接口的调用限制与用量边界本质上是在回答一个问题在给定的限流条件下业务应该用什么样的速率、缓存和重试策略去消费这个接口。接口能力边界输入边界idcard为必填 Query 参数类型为 string取值有两种形式6 位行政区划代码如110101。15 位或 18 位身份证号支持完整号码自动脱敏回显。这里有一个容易忽略的细节接口本身并未限制入参必须是 18 位完整身份证号6 位区划代码也可以直接查询。这意味着批量清洗场景中可以只传前 6 位减少敏感数据在网络链路上的暴露。QPS 边界接口的 QPS 上限为 10 次/秒属于网关级约束。超出限制后的具体响应格式如返回 429 还是自定义错误码以文档页为准但按照通用 HTTP 语义客户端应做好 429 处理以及指数退避重试。写作本文时文档未额外说明限流维度是单 Key 还是单 IP接入前建议在文档页确认。缓存生命周期接口说明中明确提到两层缓存省份数据按需从 CDN 拉取并本地缓存 30 天。网关 Redis 缓存 24 小时。这两层缓存对用量规划有直接参考意义。对于高频区划代码如北京市110000、上海市31000024 小时内重复请求大概率命中网关 Redis不会每次触发源站回源。对于冷门区划代码第一次访问可能触发 CDN 拉取但之后的请求会落到缓存中。需要强调的是缓存机制是性能优化手段不是正确性承诺业务侧不能将缓存命中行为作为接口可用性保障。鉴权与请求参数接口文档标注的 Header 参数为Authorization必填而官方 curl 示例使用的是X-API-Key请求头。这两种命名方式在不同网关版本中可能存在差异实际接入时优先以文档页最新说明为准避免在同一请求中重复携带语义等价的 Header。Query 参数只有idcard一个按照文档示例参数必填类型说明idcard是string6 位区划代码或 15/18 位身份证号建议在客户端先对参数做一次正则校验格式不合法时直接短路返回不要发往网关。无效请求同样占用 QPS 配额在高并发场景下每一条无用请求都是在挤压有效业务的空间。curl 接入示例以下示例使用 6 位区划代码110101查询请求头采用官方 curl 示例中的X-API-Keyexport IDCARD_QUERY_KEYyour_key_here curl -sS \ -X GET \ -H X-API-Key: $IDCARD_QUERY_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101若传入完整 18 位身份证号返回体中的idcard字段会以脱敏形式回显格式如110101************避免敏感信息落入调用方日志。注意请将${IDCARD_QUERY_KEY}替换为实际可用的密钥关于完整号码是否做校验位验证文档未明确说明以接口实际行为为准。响应结构解读响应示例中的核心结构如下{ code: 0, data: { province: { code: 110000, name: 北京市 }, city: { code: 110100, name: 北京市 }, district: { code: 110101, name: 东城区 }, idcard: 110101************ }, msg: 成功 }字段含义如下表所示字段类型说明codenumber业务状态码0表示成功msgstring状态描述data.province.codestring省级区划代码data.province.namestring省级名称data.city.codestring市级区划代码data.city.namestring市级名称data.district.codestring区级区划代码data.district.namestring区级名称data.idcardstring脱敏后的身份证号需要注意行政区划代码会随国家行政区划调整而变化例如撤县设区、地级市更名等。接口是否实时同步这类变更在文档中不可见业务侧应把接口返回结果作为参考数据而不是永久不变的静态事实。常见错误与限流处理虽然文档没有给出完整的错误码表但按照通用 HTTP 语义可以按以下思路排查HTTP 状态码常见原因处理方式400idcard参数缺失或格式非法检查参数校验正则401/403密钥缺失、失效或在请求头中放错位置核对X-API-Key与Authorization的使用方式429超过 QPS 上限10 次/秒指数退避重试降低并发5xx网关或源站异常退避重试若持续失败转移流量到降级方案限流场景下不建议使用固定间隔重试。固定间隔会导致多个客户端在同一时间点集中重试产生惊群效应进一步加剧限流。推荐使用指数退避加抖动jittersleep min(max_backoff, base * 2 ^ attempt) random(0, 200ms)重试次数建议控制在 2 到 3 次以内超过后应快速失败并进入降级逻辑而不是无限阻塞调用方线程。工程化注意事项客户端本地缓存服务端已有 CDN 与 Redis 双层缓存但客户端完全依赖服务端缓存并不能减少网络往返。对于高频区划代码业务侧可以增加一层本地缓存例如 TTL 设置为 24 小时与网关 Redis 的缓存周期保持一致。这样在批量场景中同一个区划代码只需要穿透到网关一次。批量任务的容量规划假设有 20 万条存量数据需要清洗QPS 上限为 10 次/秒。理想情况下理论耗时为200000 / 10 20000 秒 ≈ 5.6 小时但这只是理论下限。实际容量规划时建议预留 20% 到 30% 的余量将请求速率控制在每秒 7 到 8 次避免突发请求直接触发限流。可以用信号量或令牌桶在应用层做速率限制import os import time import random import requests API_URL https://v1.apizero.cn/api/idcard-region API_KEY os.environ[IDCARD_QUERY_KEY] def query_idcard_region(idcard: str, max_retries: int 2) - dict: 带退避重试的归属地查询最多重试 2 次。 for attempt in range(max_retries 1): resp requests.get( API_URL, params{idcard: idcard}, headers{X-API-Key: API_KEY}, timeout3, ) if resp.status_code 200: payload resp.json() if payload.get(code) 0: return payload[data] raise RuntimeError(f业务错误: {payload.get(msg)}) if resp.status_code in (429, 500, 502, 503, 504) and attempt max_retries: time.sleep(2 ** attempt random.uniform(0, 0.5)) continue resp.raise_for_status() raise RuntimeError(重试次数耗尽查询失败)注意IDCARD_QUERY_KEY必须从环境变量或密钥管理服务中读取不要硬编码到代码仓库中。脚本中的重试仅针对限流和 5xx 类瞬时错误对于 400 一类参数错误重试没有意义应当直接暴露给上层处理。日志与隐私身份证号属于敏感个人信息。两点建议业务日志中不要打印完整身份证号统一记录脱敏形式。如果 URL 中携带完整 18 位身份证号该地址会进入网关访问日志。建议在服务端聚合查询后再转发给接口避免在客户端与网关之间直接透传完整号码。降级方案当连续重试仍然失败时核心业务链路不应被卡死。常见的做法是准备一份只读的行政区划对照表作为兜底数据查询失败时回退到本地表同时记录失败样本待接口恢复后异步补刷。这样既保证主流程可用性又不把外部接口的瞬时故障扩散为业务故障。参考文档文档页https://apizero.cn/aidocs/idcard-region原始文档https://apizero.cn/aidocs/idcard-region/raw.md 身份证归属地查询接口的调用限制与用量边界：QPS、缓存生命周期与重试设计
适用场景与调用压力特征身份证归属地查询接口接收身份证号前 6 位区划代码返回省、市、区三级行政区划信息。这类能力通常出现在以下三类业务中表单地址自动回填用户在准备或实名认证页面输入身份证号后前端先调用接口补全省市区减少手动输入。数据治理与清洗存量用户表中只有身份证号、缺失地域字段时需要批量反查归属地并落库。风控策略辅助运营或风控系统将归属地与 IP 属地、收货地址做交叉比对用于异常行为识别。三类场景的请求特征差异很大。表单回填多为稀疏请求峰值集中在业务高峰时段批量清洗则是连续密集请求容易在短时间内打满接口的 QPS 上限。理解接口的调用限制与用量边界本质上是在回答一个问题在给定的限流条件下业务应该用什么样的速率、缓存和重试策略去消费这个接口。接口能力边界输入边界idcard为必填 Query 参数类型为 string取值有两种形式6 位行政区划代码如110101。15 位或 18 位身份证号支持完整号码自动脱敏回显。这里有一个容易忽略的细节接口本身并未限制入参必须是 18 位完整身份证号6 位区划代码也可以直接查询。这意味着批量清洗场景中可以只传前 6 位减少敏感数据在网络链路上的暴露。QPS 边界接口的 QPS 上限为 10 次/秒属于网关级约束。超出限制后的具体响应格式如返回 429 还是自定义错误码以文档页为准但按照通用 HTTP 语义客户端应做好 429 处理以及指数退避重试。写作本文时文档未额外说明限流维度是单 Key 还是单 IP接入前建议在文档页确认。缓存生命周期接口说明中明确提到两层缓存省份数据按需从 CDN 拉取并本地缓存 30 天。网关 Redis 缓存 24 小时。这两层缓存对用量规划有直接参考意义。对于高频区划代码如北京市110000、上海市31000024 小时内重复请求大概率命中网关 Redis不会每次触发源站回源。对于冷门区划代码第一次访问可能触发 CDN 拉取但之后的请求会落到缓存中。需要强调的是缓存机制是性能优化手段不是正确性承诺业务侧不能将缓存命中行为作为接口可用性保障。鉴权与请求参数接口文档标注的 Header 参数为Authorization必填而官方 curl 示例使用的是X-API-Key请求头。这两种命名方式在不同网关版本中可能存在差异实际接入时优先以文档页最新说明为准避免在同一请求中重复携带语义等价的 Header。Query 参数只有idcard一个按照文档示例参数必填类型说明idcard是string6 位区划代码或 15/18 位身份证号建议在客户端先对参数做一次正则校验格式不合法时直接短路返回不要发往网关。无效请求同样占用 QPS 配额在高并发场景下每一条无用请求都是在挤压有效业务的空间。curl 接入示例以下示例使用 6 位区划代码110101查询请求头采用官方 curl 示例中的X-API-Keyexport IDCARD_QUERY_KEYyour_key_here curl -sS \ -X GET \ -H X-API-Key: $IDCARD_QUERY_KEY \ https://v1.apizero.cn/api/idcard-region?idcard110101若传入完整 18 位身份证号返回体中的idcard字段会以脱敏形式回显格式如110101************避免敏感信息落入调用方日志。注意请将${IDCARD_QUERY_KEY}替换为实际可用的密钥关于完整号码是否做校验位验证文档未明确说明以接口实际行为为准。响应结构解读响应示例中的核心结构如下{ code: 0, data: { province: { code: 110000, name: 北京市 }, city: { code: 110100, name: 北京市 }, district: { code: 110101, name: 东城区 }, idcard: 110101************ }, msg: 成功 }字段含义如下表所示字段类型说明codenumber业务状态码0表示成功msgstring状态描述data.province.codestring省级区划代码data.province.namestring省级名称data.city.codestring市级区划代码data.city.namestring市级名称data.district.codestring区级区划代码data.district.namestring区级名称data.idcardstring脱敏后的身份证号需要注意行政区划代码会随国家行政区划调整而变化例如撤县设区、地级市更名等。接口是否实时同步这类变更在文档中不可见业务侧应把接口返回结果作为参考数据而不是永久不变的静态事实。常见错误与限流处理虽然文档没有给出完整的错误码表但按照通用 HTTP 语义可以按以下思路排查HTTP 状态码常见原因处理方式400idcard参数缺失或格式非法检查参数校验正则401/403密钥缺失、失效或在请求头中放错位置核对X-API-Key与Authorization的使用方式429超过 QPS 上限10 次/秒指数退避重试降低并发5xx网关或源站异常退避重试若持续失败转移流量到降级方案限流场景下不建议使用固定间隔重试。固定间隔会导致多个客户端在同一时间点集中重试产生惊群效应进一步加剧限流。推荐使用指数退避加抖动jittersleep min(max_backoff, base * 2 ^ attempt) random(0, 200ms)重试次数建议控制在 2 到 3 次以内超过后应快速失败并进入降级逻辑而不是无限阻塞调用方线程。工程化注意事项客户端本地缓存服务端已有 CDN 与 Redis 双层缓存但客户端完全依赖服务端缓存并不能减少网络往返。对于高频区划代码业务侧可以增加一层本地缓存例如 TTL 设置为 24 小时与网关 Redis 的缓存周期保持一致。这样在批量场景中同一个区划代码只需要穿透到网关一次。批量任务的容量规划假设有 20 万条存量数据需要清洗QPS 上限为 10 次/秒。理想情况下理论耗时为200000 / 10 20000 秒 ≈ 5.6 小时但这只是理论下限。实际容量规划时建议预留 20% 到 30% 的余量将请求速率控制在每秒 7 到 8 次避免突发请求直接触发限流。可以用信号量或令牌桶在应用层做速率限制import os import time import random import requests API_URL https://v1.apizero.cn/api/idcard-region API_KEY os.environ[IDCARD_QUERY_KEY] def query_idcard_region(idcard: str, max_retries: int 2) - dict: 带退避重试的归属地查询最多重试 2 次。 for attempt in range(max_retries 1): resp requests.get( API_URL, params{idcard: idcard}, headers{X-API-Key: API_KEY}, timeout3, ) if resp.status_code 200: payload resp.json() if payload.get(code) 0: return payload[data] raise RuntimeError(f业务错误: {payload.get(msg)}) if resp.status_code in (429, 500, 502, 503, 504) and attempt max_retries: time.sleep(2 ** attempt random.uniform(0, 0.5)) continue resp.raise_for_status() raise RuntimeError(重试次数耗尽查询失败)注意IDCARD_QUERY_KEY必须从环境变量或密钥管理服务中读取不要硬编码到代码仓库中。脚本中的重试仅针对限流和 5xx 类瞬时错误对于 400 一类参数错误重试没有意义应当直接暴露给上层处理。日志与隐私身份证号属于敏感个人信息。两点建议业务日志中不要打印完整身份证号统一记录脱敏形式。如果 URL 中携带完整 18 位身份证号该地址会进入网关访问日志。建议在服务端聚合查询后再转发给接口避免在客户端与网关之间直接透传完整号码。降级方案当连续重试仍然失败时核心业务链路不应被卡死。常见的做法是准备一份只读的行政区划对照表作为兜底数据查询失败时回退到本地表同时记录失败样本待接口恢复后异步补刷。这样既保证主流程可用性又不把外部接口的瞬时故障扩散为业务故障。参考文档文档页https://apizero.cn/aidocs/idcard-region原始文档https://apizero.cn/aidocs/idcard-region/raw.md