<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 身份证归属地查询

> 根据身份证号前 6 位查询省/市/区三级归属地。支持完整 18 位身份证号自动脱敏回显。省份数据按需从 CDN 拉取并本地缓存 30 天，网关 Redis 缓存 24h。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `idcard-region` |
| 接口名称 | 身份证归属地查询 |
| 接口地址 | `https://v1.apizero.cn/api/idcard-region` |
| 请求方法 | `GET` |
| 分类 | kyc |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 100 次（已认证用户） |
| 匿名每日额度 | 0 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

需要登录 API Key（kyc 类默认关闭匿名访问）。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `idcard` | `string` | 是 | 6 位区划代码或 15/18 位身份证号 | `110101` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 是 | — | — |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/idcard-region?idcard=110101&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `idcard` | `string` | 号码（>6 位时尾部以 * 脱敏） | — |
| `province.code` | `string` | 省份代码 | — |
| `province.name` | `string` | 省份名称 | — |
| `city.code` | `string` | 城市代码 | — |
| `city.name` | `string` | 城市名称 | — |
| `district.code` | `string` | 区县代码（部分老号码可能缺失） | — |
| `district.name` | `string` | 区县名称 | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "idcard": "110101************",
        "province": {
            "code": "110000",
            "name": "北京市"
        },
        "city": {
            "code": "110100",
            "name": "北京市"
        },
        "district": {
            "code": "110101",
            "name": "东城区"
        }
    }
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | idcard 格式无效（应为 6/15/18 位） |
| `4000` | `—` | 未找到该省份/区县数据 |
| `5020` | `—` | CDN 上游不可用 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线 · 三级归属地 + 30 天文件缓存

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/idcard-region`

Source: `https://apizero.cn/aidocs/idcard-region/raw.md`
Last updated: 2026-05-12T05:43:07+08:00