「身份证信息提取」是数据鱼API平台提供的中国居民身份证号解析接口,Base 路径 /api/idcard,共 3 个端点。服务按 GB 11643-1999 校验 18 位结构,用 ISO 7064 MOD11-2 验校验码,解析行政区划、出生日期、年龄、性别、生肖与星座,并给出合规及风险标记;15 位号码会先补「19」转成 18 位。实现为纯离线计算,不落库原号,analyze 默认返回脱敏号码。
它解决的是「拿到一串号码后如何结构化」的问题,不核验姓名、照片或签发机关,也不连接公安人口库。analyze 返回完整解析,validate 只判断号码是否可能是真实号码,ping 用于探活。两个业务端点均为 POST,号码应放在请求体,不要拼进 URL,以免进入浏览器历史、代理日志与 Referer。
身份证号属于敏感个人信息,接口能力越直接,调用方的合规责任越重。本文只描述接口行为,不构成法律意见;实际接入应有明确业务目的、合法依据与最小化采集策略。
方法 | 路径 | 说明 | 鉴权 |
|---|---|---|---|
GET | /api/idcard/ping | 健康检查 | 需要 |
POST | /api/idcard/analyze | 解析号码,返回地区、生日、年龄、性别、生肖、星座与风险 | 需要 |
POST | /api/idcard/validate | 校验号码结构、校验位与生日 | 需要 |
鉴权使用 X-API-Key 请求头或 ?api_key= 查询参数,缺失返回 4011,无效返回 4013,3 条路由包括 ping 都需要 Key。响应统一为 {code, msg, data},code 为 0 表示成功;缺少 id_card 返回 4001,analyze 的号码格式非法返回 4002,路由不存在为 4040,方法不允许为 4050。
analyze 与 validate 均为 POST,参数放在 JSON body 或表单中,参数名统一为 id_card。服务端调用应走 HTTPS,API Key 只保存在服务端;不要在前端直接调用,也不要把完整号码写进访问日志、埋点或错误上报。
用途:把 15 位或 18 位身份证号拆成可读字段,并附带风险与场景合规判断。
参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
id_card | string | 是 | 15 位或 18 位身份证号码 |
scene | string | 否 | finance、game、social,影响合规判定 |
raw | bool | 否 | 是否返回原号,默认 false,只返回脱敏号 |
check_at | string | 否 | 参考时间,ISO8601,用于年龄、未来生日与游戏禁玩时段 |
返回字段 | 类型 | 说明 |
|---|---|---|
idcard | string | 默认脱敏号;raw=true 时为原号 |
masked | string | 固定脱敏号,保留前 6 后 4 |
version | string | 15 或 18 |
is_valid_format | bool | 18 位长度、字符与末位 X 是否合法 |
checksum_ok | bool | MOD11-2 校验位是否一致 |
region | object | province、city、district、code 与 region_known |
birthday | string | 出生日期,YYYY-MM-DD |
age / age_stage | int / string | 周岁与年龄段 |
gender | string | male 或 female |
zodiac / constellation | string | 生肖与星座 |
compliance | object | is_adult、game_ban_window、needs_manual_review |
risk | object | score(0-100)、level、hit_rules |
格式非法时返回 HTTP 400、code 4002,但 data 仍给出同一结构,is_valid_format=false、risk=100/block;校验码不匹配不会让 analyze 报错,而是 code 0、checksum_ok=false、risk=100。调用方不能只看 code,还要检查 is_valid_format 与 checksum_ok,或直接以 risk.level 是否 block 作为拦截条件。
行政区划码内嵌 303 条,覆盖直辖市与主要城市的区县,未收录时 region_known=false,risk 至少 15。region 只来自号码前六位,不能当作现住址或户籍证明。18 位生日限定在 1900 年至当前年,未来生日记 100 分;15 位号码固定补 19,因此只能表示 1900 年代出生。
年龄按 check_at 或当前时间计算周岁,生日未到减一岁;age_stage 分为 minor_under_8、minor_8_16、minor_16_18、adult、senior。日期边界、闰日与 check_at 时区会影响结果。scene=finance 时,校验位错误或地区未知会置 needs_manual_review;scene=game 时按参考小时判断 22:00 至次日 08:00 的禁玩窗口,并给出 is_adult。risk 在 20、50、80 分处分 medium、high、block,黑名单测试号、格式错误、校验位错误与未来生日直接 100 分。
POST /api/idcard/analyze?api_key=YOUR_KEY
Content-Type: application/json
{"id_card":"110101199001011237","scene":"finance","check_at":"2026-01-01T00:00:00+08:00"}{valid, error}。它校验长度、字符、校验位与生日,不检查地区码是否收录,也不检查测试号黑名单。原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。