<!-- 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 -->

# 中文地址解析

> 一行 API 从中文地址字符串中提取「省市区街道 + 详细地址 + 姓名 + 手机号 + 邮编」。

适用场景：电商收货地址自动拆分、快递下单页智能填充、CRM 客户资料清洗、办公地址结构化入库。

特点：纯本地正则算法，无任何上游依赖，毫秒级响应；支持 34 个省级行政区及其简称识别（如「北京」→「北京市」、「新疆」→「新疆维吾尔自治区」）；支持快递场景下「张三 138xxxxxxxx 上海市浦东新区xx路xx号 200000」这类混合输入的自动拆分。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `address-parse` |
| 接口名称 | 中文地址解析 |
| 接口地址 | `https://v1.apizero.cn/api/address-parse` |
| 请求方法 | `POST` |
| 分类 | geo |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 20 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 100 次（无 API Key） |
| VIP 免费 | 是 |
| 调用总次数 | undefined |

## 2. 认证

未登录匿名 1 QPS · 50 次/日；已登录默认 20 QPS · 1000 次/日（按账号等级浮动）

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

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `address` | `string` | 是 | 中文地址字符串。支持姓名/手机/邮编混合输入，长度 ≤ 500 | `张三 13812345678 上海市浦东新区张江镇科苑路88号 201203` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer sk_live_xxx（可选；未登录匿名调用受更严格的限流） | — |

## 5. 请求示例 (cURL)

```bash
curl -X POST "https://v1.apizero.cn/api/address-parse" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address": "张三 13812345678 上海市浦东新区张江镇科苑路88号 201203"
}'
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `data.original` | `string` | 原始输入地址（未做任何处理） | — |
| `data.province` | `string` | 省 / 直辖市 / 自治区 / 特别行政区全称 | — |
| `data.city` | `string` | 地级市 / 州 / 盟 / 地区（直辖市等于省） | — |
| `data.district` | `string` | 区 / 县 / 县级市 / 旗 | — |
| `data.street` | `string` | 街道 / 乡 / 镇 / 路 / 大道 / 街 / 巷 / 弄 | — |
| `data.detail` | `string` | 门牌号 / 楼栋 / 单元等详细地址 | — |
| `data.zipcode` | `string` | 邮政编码（未识别时为空字符串） | — |
| `data.phone` | `string` | 手机号（未识别时为空字符串） | — |
| `data.name` | `string` | 收件人姓名（未识别时为空字符串） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "original": "张三 138****1234 上海市浦东新区张江镇科苑路88号 201203",
        "province": "上海市",
        "city": "上海市",
        "district": "浦东新区",
        "street": "张江镇",
        "detail": "科苑路88号",
        "zipcode": "201203",
        "phone": "138****1234",
        "name": "张三"
    },
    "request_id": "kx8n9q2a1b3c4d5e6f7g"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `0` | `成功` | 解析成功 |
| `4000` | `参数错误` | 缺少 address 参数或长度超出 500 |
| `4015` | `未授权` | 此接口需要 API Key 才能调用（仅对已关闭匿名的账号生效） |
| `4029` | `限流` | QPS 超限，请降低调用频率 |
| `4030` | `配额用尽` | 今日免费额度已用完，请明日再试或升级套餐 |

## 9. 变更日志

- **1.0.0** (2026-05-04)
  - 首次发布：支持 34 个省级行政区（含简称）解析
  - 支持嵌入式快递地址解析（姓名 / 手机号 / 邮编混合输入）
  - 纯本地正则，毫秒级响应，无上游依赖

---

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

Source: `https://apizero.cn/aidocs/address-parse/raw.md`
Last updated: 2026-05-11T16:16:07+08:00