快速开始
从注册到第一次成功调用,三步。接口基地址是 https://api.yuanputech.com/area/v1,响应为 JSON(UTF-8),正式环境只支持 HTTPS。
第一步:获取 API Key
第二步:第一次调用
把 Key 放进 X-API-Key 请求头,查一条区划详情。下面这段可以直接复制运行,把 Key 换成你自己的。
curl "https://api.yuanputech.com/area/v1/regions/110105" \
-H "X-API-Key: $YUANPU_API_KEY" \
-H "Accept: application/json"拿到 "code": 0 就说明接通了。这一次调用会扣减 1 次额度。
第三步:处理 402,提示续费
额度用尽或套餐到期时接口返回 HTTP 402,响应里的 data.renew_url 是续费页面地址。请单独处理这一类,不要当成通用错误重试,重试不会成功。
const res = await fetch(url, { headers });
const body = await res.json();
if (res.status === 402) {
// 40201 无有效套餐 / 40202 额度用尽 / 40203 超出当日限额
// 重试无用:记录日志,把 data.renew_url(续费页地址)发给运维
logger.error("区划接口额度问题", {
code: body.code,
requestId: body.request_id,
renewUrl: body.data?.renew_url
});
throw new QuotaError(body.message);
}
if (res.status === 429) {
// 42901 请求过于频繁,不计费,按 Retry-After 退避后重试
await sleep(Number(res.headers.get("Retry-After") ?? 1) * 1000);
return retry();
}
if (body.code !== 0) {
throw new ApiError(body.code, body.message);
}
return body.data;鉴权
所有接口都用 API Key 鉴权,通过 X-API-Key 请求头传入,值就是 Key 本身,不带任何前缀。为兼容旧版接入,服务端同时接受 Authorization: Bearer <your-key>,两种写法等效,新接入请统一用 X-API-Key。不支持放在查询参数里。
Key 的格式
Key 以 ak_live_ 开头,在控制台创建。每个 Key 可以单独命名、配置 IP 白名单、停用或重置。
- 所有 Key 都调用正式数据、扣减账号的真实额度,没有单独的测试环境 Key。
- 建议每个服务或部署环境各用一个 Key,出问题时可以单独停用,不影响其他接入。
- 可创建的 Key 数量取决于套餐:免费试用 1 个、按量充值 3 个、包月与包季 5 个、包年 10 个。
IP 白名单
每个 Key 可以单独配置 IP 白名单。配置后,来源 IP 不在名单内的请求会返回 40301,不计费。
- 留空表示不限制来源,仅建议用于本地调试。
- 生产环境建议填写服务器出口 IP,支持单个 IP 与 CIDR 网段(IPv4 / IPv6)。
- 修改白名单后立即生效,不需要重建 Key。
鉴权失败的三种情况
| 业务码 | HTTP | 含义 | 怎么处理 |
|---|---|---|---|
40101 | 401 | 缺少 API Key | 检查是否带上了 X-API-Key 请求头 |
40102 | 401 | Key 无效 | 确认是否复制完整,是否误用了已重置的旧 Key |
40103 | 401 | Key 已停用 | 在控制台恢复或新建一个 Key |
计费与额度
只有成功调用才扣减额度。完整的价格与套餐对比在定价页。
什么算一次成功调用
判定标准是 HTTP 200 且响应体里的 code 等于 0。
- 计费:成功返回数据的调用,包括命中缓存的调用(响应头
X-Cache: HIT)。 - 不计费:参数错误(
40001)、鉴权失败(401xx)、IP 不在白名单(40301)、套餐不含该接口(40302)、Key 不属于此项目(40303)、区划不存在(40401)、请求过于频繁(42901)、额度问题(402xx)、服务端错误(5xx)。 - 批量查询:按请求里传入的代码个数计费(重复的代码只计一次,44 与 440000000000 视为同一个),传 50 个不同代码计 50 次,与查到几个无关。
额度的扣减顺序
- 先扣试用和订阅额度(免费试用、包月、包季、包年)。多个同时有效时,先到期的先扣。
- 用尽后再扣充值余额,同样先到期的先扣。充值余额自到账日起 1 年内有效。
- 包月套餐有 2 万次 / 天 的日上限,超出返回
40203,次日零点(北京时间)重置。
每次成功调用的响应头 X-Quota-Remaining 会返回剩余可用次数(所有有效套餐合计,-1 表示不限),可以据此提前告警。
到期或用完
| 业务码 | HTTP | 含义 | 恢复方式 |
|---|---|---|---|
40201 | 402 | 没有有效套餐 | 开通试用、充值或购买订阅 |
40202 | 402 | 额度已用尽 | 充值或升级套餐,即时恢复 |
40203 | 402 | 超出当日限额 | 次日零点重置,或升级到不设日上限的套餐 |
402 响应的 data.renew_url 是续费 / 订购页面的地址,可以直接放进告警消息。续费后 API Key、IP 白名单和所有配置都不变,不需要重新接入。
区划详情
按区划代码查询单条记录,返回名称、层级、上级代码、完整名称与从省级到自身的路径。省市区联动里用来回填已有地址,或校验历史数据中的代码是否仍然有效。
请求参数
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
code | path | string | 必填 | 统计用区划代码,标准长度 12 位:省 2 位、市 2 位、县 2 位、乡镇 3 位、村 3 位。也接受 2 / 4 / 6 / 9 位短码,右侧自动补零,例如 110105 等同于 110105000000。 |
version | query | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
code | integer | 业务状态码,0 表示成功。注意与 data.code 不是同一个字段。 |
message | string | 可读提示。成功时为 "ok"。 |
request_id | string | 本次请求的唯一标识(UUID),与响应头 X-Request-Id 相同。反馈问题时请一并提供。 |
data.code | string | 12 位区划代码。传入短码时返回补齐后的代码。 |
data.name | string | 区划名称,使用国家统计局公布的标准名称。 |
data.level | integer | 层级:1 省级、2 地级、3 县级、4 乡级、5 村级。 |
data.level_name | string | 层级的中文名称(省级 / 地级 / 县级 / 乡级 / 村级),与 level 一一对应。 |
data.parent_code | string / null | 上级区划代码(12 位)。省级为 null。 |
data.category | integer / null | 城乡分类代码,仅村级返回,其他级别为 null。取值见数据说明。 |
data.category_name | string / null | 城乡分类名称:111 主城区、112 城乡结合区、121 镇中心区、122 镇乡结合区、123 特殊区域、210 乡中心区、220 村庄。 |
data.full_name | string | 完整名称,例如 北京市朝阳区。「市辖区」「县」「省直辖县级行政区划」这类上级占位名称不拼进去。 |
data.path | array | 从省级到自身的路径,每个元素含 code、name、level。长度不固定:东莞、中山、嘉峪关、儋州这类不设区的地级市会跳过县级,请按 level 读取,不要按下标取值。仅详情与批量查询返回。 |
响应示例
{
"code": 0,
"message": "ok",
"data": {
"code": "110105000000",
"name": "朝阳区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区",
"path": [
{ "code": "110000000000", "name": "北京市", "level": 1 },
{ "code": "110100000000", "name": "市辖区", "level": 2 },
{ "code": "110105000000", "name": "朝阳区", "level": 3 }
]
},
"request_id": "01a1de45-b941-7023-ad31-ad6eb03fcaf8"
}代码示例
# 查询北京市朝阳区
curl "https://api.yuanputech.com/area/v1/regions/110105" \
-H "X-API-Key: $YUANPU_API_KEY" \
-H "Accept: application/json"const res = await fetch(
"https://api.yuanputech.com/area/v1/regions/110105",
{ headers: { "X-API-Key": process.env.YUANPU_API_KEY } }
);
const body = await res.json();
if (body.code !== 0) throw new Error(body.message);
console.log(body.data.full_name); // 北京市朝阳区
console.log(body.data.path.map(n => n.name).join(" / "));
// 北京市 / 市辖区 / 朝阳区(path 长度不固定,请按 level 读取)import os
import requests
resp = requests.get(
"https://api.yuanputech.com/area/v1/regions/110105",
headers={"X-API-Key": os.environ["YUANPU_API_KEY"]},
timeout=5,
)
resp.raise_for_status()
body = resp.json()
if body["code"] != 0:
raise RuntimeError(body["message"])
data = body["data"]
print(data["name"], data["level_name"]) # 朝阳区 县级
print(" / ".join(n["name"] for n in data["path"]))var client = HttpClient.newHttpClient();
var req = HttpRequest.newBuilder()
.uri(URI.create("https://api.yuanputech.com/area/v1/regions/110105"))
.header("X-API-Key", System.getenv("YUANPU_API_KEY"))
.header("Accept", "application/json")
.timeout(Duration.ofSeconds(5))
.GET()
.build();
var res = client.send(req, BodyHandlers.ofString());
if (res.statusCode() == 402) {
throw new IllegalStateException("额度问题,请先续费");
}
System.out.println(res.body());req, _ := http.NewRequest(http.MethodGet,
"https://api.yuanputech.com/area/v1/regions/110105", nil)
req.Header.Set("X-API-Key", os.Getenv("YUANPU_API_KEY"))
client := &http.Client{Timeout: 5 * time.Second}
resp, err := client.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode == http.StatusPaymentRequired {
log.Fatal("额度问题,请先续费")
}
var body struct {
Code int `json:"code"`
Message string `json:"message"`
Data struct {
FullName string `json:"full_name"`
} `json:"data"`
}
json.NewDecoder(resp.Body).Decode(&body)
fmt.Println(body.Data.FullName) // 北京市朝阳区<?php
$ch = curl_init("https://api.yuanputech.com/area/v1/regions/110105");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("YUANPU_API_KEY"),
"Accept: application/json",
],
CURLOPT_TIMEOUT => 5,
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($body["code"] !== 0) {
throw new RuntimeException($body["message"]);
}
echo $body["data"]["full_name"];在线调试
填入你的 API Key 和区划代码,浏览器会直接请求网关,下面显示的状态码、响应头和 JSON 都是真实结果。成功调用会照常扣减 1 次额度,与正式接入一致。
下级列表
取某个区划的直接下级,按代码排序。省市区三级联动最常用的接口,一次请求返回一层。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
code | path | string | 必填 | 上级区划代码(2 / 4 / 6 / 9 / 12 位)。查全国省份请用条件列表 ?level=1。 |
page | query | integer | 可选 | 页码,从 1 开始,默认 1。 |
size | query | integer | 可选 | 每页条数,默认 100,最大 1000。 |
version | query | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
直辖市的下级是「市辖区」这一层(level 2),再往下才是各区;东莞、中山、嘉峪关、儋州这类不设区的地级市,下级直接是街道和镇(level 4)。请按返回的 level 判断,不要按固定层数处理。
响应示例
分页结构 { items, total, page, size },items 里的区划对象与详情相同,但不含 path。
{
"code": 0,
"message": "ok",
"data": {
"items": [
{
"code": "110105001000",
"name": "建外街道",
"level": 4,
"level_name": "乡级",
"parent_code": "110105000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区建外街道"
},
{
"code": "110105002000",
"name": "朝外街道",
"level": 4,
"level_name": "乡级",
"parent_code": "110105000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区朝外街道"
}
],
"total": 43,
"page": 1,
"size": 2
},
"request_id": "01a1de45-c3d2-7a10-8e5f-2b7c90d41e66"
}条件列表
按层级、上级代码和城乡分类筛选并分页,适合批量拉取某一层的全部数据,例如一次取全国 343 个地级行政区。返回结构与下级列表相同。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
level | integer | 可选 | 限定层级,1 到 5。例如全部省份:?level=1。 |
pcode | string | 可选 | 限定上级区划代码。与 level 可同时使用。对应响应里的 parent_code 字段。 |
category | integer | 可选 | 按城乡分类代码筛选,取值 111 / 112 / 121 / 122 / 123 / 210 / 220,含义见数据说明。只有村级(level=5)记录带该字段,其他层级传了不会有结果。 |
page | integer | 可选 | 页码,默认 1。 |
size | integer | 可选 | 每页条数,默认 100,最大 1000。 |
version | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
每翻一页都是一次独立调用,各计 1 次。拉取村级全量(620,572 条)前请先估算额度。
名称搜索
按名称模糊匹配,用于把历史数据里「朝阳」「北京朝阳区」这类非标准写法映射到权威代码。排序为:完全匹配优先,其次前缀匹配,再按层级和代码。返回区划对象数组(不含 path)。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
keyword | string | 必填 | 搜索词,1 到 32 个字符。 |
level | integer | 可选 | 限定层级,缩小范围。 |
within | string | 可选 | 限定在某个区划范围内搜索,传上级区划代码。例如 within=11 只在北京市范围内匹配,用来消解同名区划。 |
limit | integer | 可选 | 返回条数,默认 20,最大 50。 |
version | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
同名区划在全国并不少见(例如多个「城关区」)。返回结果带 full_name 与 parent_code,请结合上级名称再做确认,不要直接取第一条。
子树
一次导出某个节点往下若干层的完整子树,适合把一个省或市的数据同步到自己的库里。返回根节点的区划对象,每个节点的 children 是下一层节点数组。
| 参数 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
code | path | string | 必填 | 子树根节点的区划代码。 |
depth | query | integer | 可选 | 往下展开的层数,取值 1 或 2,默认 1。 |
version | query | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
一次请求只计 1 次,不论返回多少节点。用它代替逐级遍历可以显著省额度。响应体可能较大,建议开启 gzip。
批量查询
一次请求查多个代码,减少网络往返。按请求里传入的代码个数计费,这是唯一一个不按请求次数计费的接口。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
codes | array<string> | 必填 | 区划代码数组(2 / 4 / 6 / 9 / 12 位),1 到 100 个。按去重后的代码个数计费(44 与 440000000000 视为同一个)。 |
version | string | 可选 | 数据版本(年度),默认取当前版本 2024。 |
curl -X POST "https://api.yuanputech.com/area/v1/regions/batch" \
-H "X-API-Key: $YUANPU_API_KEY" \
-H "Content-Type: application/json" \
-d '{"codes":["110105","441900","999999"]}'
# 本次计费 3 次:按传入的代码个数计,查不到的 999999 也计入响应示例
items 是查到的区划详情(含 path),not_found 是没有查到的代码(补齐为 12 位),方便定位上游脏数据。
{
"code": 0,
"message": "ok",
"data": {
"items": [
{
"code": "110105000000",
"name": "朝阳区",
"level": 3,
"level_name": "县级",
"parent_code": "110100000000",
"category": null,
"category_name": null,
"full_name": "北京市朝阳区",
"path": [
{ "code": "110000000000", "name": "北京市", "level": 1 },
{ "code": "110100000000", "name": "市辖区", "level": 2 },
{ "code": "110105000000", "name": "朝阳区", "level": 3 }
]
},
{
"code": "441900000000",
"name": "东莞市",
"level": 2,
"level_name": "地级",
"parent_code": "440000000000",
"category": null,
"category_name": null,
"full_name": "广东省东莞市",
"path": [
{ "code": "440000000000", "name": "广东省", "level": 1 },
{ "code": "441900000000", "name": "东莞市", "level": 2 }
]
}
],
"not_found": ["999999000000"]
},
"request_id": "01a1de45-d07a-7b2e-9c41-6f0e3a8b52d1"
}错误码
HTTP 状态码表示错误的大类,响应体里的 code 表示具体原因。code = 0 才是成功。
| 业务码 | HTTP | 含义 | 是否计费 | 怎么处理 |
|---|---|---|---|---|
0 | 200 | 成功 | 计费 | 读取 data。 |
40001 | 400 | 参数错误 | 不计费 | 按 message 和 data.errors(字段级说明)修正参数,不要重试。 |
40101 | 401 | 缺少 API Key | 不计费 | 检查是否带上了 X-API-Key 请求头。 |
40102 | 401 | API Key 无效 | 不计费 | 确认 Key 是否复制完整、是否误用了已重置的旧 Key。 |
40103 | 401 | API Key 已停用 | 不计费 | 在控制台恢复该 Key,或新建一个。 |
40201 | 402 | 无有效套餐 | 不计费 | 开通试用、充值或购买订阅(见 data.renew_url)。不要重试。 |
40202 | 402 | 额度已用尽 | 不计费 | 充值或升级套餐,即时恢复。不要重试。 |
40203 | 402 | 超出当日限额 | 不计费 | 次日零点重置,或换用不设日上限的套餐。 |
40301 | 403 | IP 不在白名单 | 不计费 | 把服务器出口 IP 加进该 Key 的白名单。 |
40302 | 403 | 套餐不含该接口 | 不计费 | 升级到包含该接口的套餐。 |
40303 | 403 | Key 不属于此项目 | 不计费 | 换用在本项目下创建的 Key。 |
40401 | 404 | 区划不存在 | 不计费 | 确认代码是否属于当前数据版本,历史撤并的代码可能已不存在。 |
42901 | 429 | 请求过于频繁 | 不计费 | 按响应头 Retry-After 退避后重试,或升级套餐提高 QPS。 |
50001 / 50301 | 500 / 503 | 服务端错误 / 暂不可用 | 不计费 | 稍后重试;持续出现请带上 request_id 联系技术支持。 |
错误响应示例
{
"code": 40202,
"message": "调用额度已用尽,请订购或续费",
"data": {
"project": "area",
"renew_url": "/console/projects/area/plans"
},
"request_id": "01a1de46-2c0e-7d51-9b8a-4f3c2e1d0a97"
}错误响应的 data 一般为 null;402 时带 renew_url(续费 / 订购页地址),40001 时带 errors(字段级说明)。反馈问题时请提供 request_id,我们能据此定位到单次请求。
更新日志
接口的不兼容变更会提前公告并保留旧版本。数据版本更新不改变接口结构,可以用 version 参数固定数据年度。
v1.0.0 · 首个版本
五级行政区划查询 API 上线,提供区划详情、下级列表、条件列表、名称搜索、子树、批量查询 6 个接口,数据版本为 2024 年度统计用区划代码,共 665,552 条。
鉴权使用 X-API-Key 请求头,接口路径统一为 /area/v1 前缀;批量查询返回 not_found 数组列出未命中的代码。