当前:快速开始

快速开始

从注册到第一次成功调用,三步。接口基地址是 https://api.yuanputech.com/area/v1,响应为 JSON(UTF-8),正式环境只支持 HTTPS。

第一步:获取 API Key

  1. 用邮箱或手机号 注册账号,同意《用户服务协议》与《隐私政策》。
  2. 在控制台开通免费试用,获得 7 天 / 1,000 次额度。
  3. 开通时会自动生成第一个 API Key,之后也可以在「API Key」页新建。完整 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 是续费页面地址。请单独处理这一类,不要当成通用错误重试,重试不会成功。

JavaScript区分 402 与其他错误
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含义怎么处理
40101401缺少 API Key检查是否带上了 X-API-Key 请求头
40102401Key 无效确认是否复制完整,是否误用了已重置的旧 Key
40103401Key 已停用在控制台恢复或新建一个 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. 用尽后再扣充值余额,同样先到期的先扣。充值余额自到账日起 1 年内有效。
  3. 包月套餐有 2 万次 / 天 的日上限,超出返回 40203,次日零点(北京时间)重置。

每次成功调用的响应头 X-Quota-Remaining 会返回剩余可用次数(所有有效套餐合计,-1 表示不限),可以据此提前告警。

到期或用完

业务码HTTP含义恢复方式
40201402没有有效套餐开通试用、充值或购买订阅
40202402额度已用尽充值或升级套餐,即时恢复
40203402超出当日限额次日零点重置,或升级到不设日上限的套餐

402 响应的 data.renew_url 是续费 / 订购页面的地址,可以直接放进告警消息。续费后 API Key、IP 白名单和所有配置都不变,不需要重新接入。

区划详情

按区划代码查询单条记录,返回名称、层级、上级代码、完整名称与从省级到自身的路径。省市区联动里用来回填已有地址,或校验历史数据中的代码是否仍然有效。

GEThttps://api.yuanputech.com/area/v1/regions/{code}计费 1 次

请求参数

参数位置类型必填说明
codepathstring必填统计用区划代码,标准长度 12 位:省 2 位、市 2 位、县 2 位、乡镇 3 位、村 3 位。也接受 2 / 4 / 6 / 9 位短码,右侧自动补零,例如 110105 等同于 110105000000。
versionquerystring可选数据版本(年度),默认取当前版本 2024。

响应字段

字段类型说明
codeinteger业务状态码,0 表示成功。注意与 data.code 不是同一个字段。
messagestring可读提示。成功时为 "ok"。
request_idstring本次请求的唯一标识(UUID),与响应头 X-Request-Id 相同。反馈问题时请一并提供。
data.codestring12 位区划代码。传入短码时返回补齐后的代码。
data.namestring区划名称,使用国家统计局公布的标准名称。
data.levelinteger层级:1 省级、2 地级、3 县级、4 乡级、5 村级。
data.level_namestring层级的中文名称(省级 / 地级 / 县级 / 乡级 / 村级),与 level 一一对应。
data.parent_codestring / null上级区划代码(12 位)。省级为 null。
data.categoryinteger / null城乡分类代码,仅村级返回,其他级别为 null。取值见数据说明。
data.category_namestring / null城乡分类名称:111 主城区、112 城乡结合区、121 镇中心区、122 镇乡结合区、123 特殊区域、210 乡中心区、220 村庄。
data.full_namestring完整名称,例如 北京市朝阳区。「市辖区」「县」「省直辖县级行政区划」这类上级占位名称不拼进去。
data.patharray从省级到自身的路径,每个元素含 code、name、level。长度不固定:东莞、中山、嘉峪关、儋州这类不设区的地级市会跳过县级,请按 level 读取,不要按下标取值。仅详情与批量查询返回。

响应示例

HTTP 200GET /area/v1/regions/110105
{
  "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"

在线调试

填入你的 API Key 和区划代码,浏览器会直接请求网关,下面显示的状态码、响应头和 JSON 都是真实结果。成功调用会照常扣减 1 次额度,与正式接入一致。

GET /area/v1/regions/{code}真实请求 · 成功计费 1 次
留空发送可以看到 40101。还没有 Key?注册并开通免费试用
支持 2/4/6/9/12 位,可试 110105、441900、441900003;填 999999 看 40401。
GET https://api.yuanputech.com/area/v1/regions/110105
还没有发送请求
响应application/json
点「发送请求」查看响应

下级列表

取某个区划的直接下级,按代码排序。省市区三级联动最常用的接口,一次请求返回一层。

GET/area/v1/regions/{code}/children计费 1 次
参数位置类型必填说明
codepathstring必填上级区划代码(2 / 4 / 6 / 9 / 12 位)。查全国省份请用条件列表 ?level=1。
pagequeryinteger可选页码,从 1 开始,默认 1。
sizequeryinteger可选每页条数,默认 100,最大 1000。
versionquerystring可选数据版本(年度),默认取当前版本 2024。

直辖市的下级是「市辖区」这一层(level 2),再往下才是各区;东莞、中山、嘉峪关、儋州这类不设区的地级市,下级直接是街道和镇(level 4)。请按返回的 level 判断,不要按固定层数处理。

响应示例

分页结构 { items, total, page, size },items 里的区划对象与详情相同,但不含 path。

HTTP 200GET /area/v1/regions/110105/children?size=2
{
  "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 个地级行政区。返回结构与下级列表相同。

GET/area/v1/regions计费 1 次
参数类型必填说明
levelinteger可选限定层级,1 到 5。例如全部省份:?level=1。
pcodestring可选限定上级区划代码。与 level 可同时使用。对应响应里的 parent_code 字段。
categoryinteger可选按城乡分类代码筛选,取值 111 / 112 / 121 / 122 / 123 / 210 / 220,含义见数据说明。只有村级(level=5)记录带该字段,其他层级传了不会有结果。
pageinteger可选页码,默认 1。
sizeinteger可选每页条数,默认 100,最大 1000。
versionstring可选数据版本(年度),默认取当前版本 2024。

每翻一页都是一次独立调用,各计 1 次。拉取村级全量(620,572 条)前请先估算额度。

子树

一次导出某个节点往下若干层的完整子树,适合把一个省或市的数据同步到自己的库里。返回根节点的区划对象,每个节点的 children 是下一层节点数组。

GET/area/v1/regions/{code}/tree计费 1 次
参数位置类型必填说明
codepathstring必填子树根节点的区划代码。
depthqueryinteger可选往下展开的层数,取值 1 或 2,默认 1。
versionquerystring可选数据版本(年度),默认取当前版本 2024。

一次请求只计 1 次,不论返回多少节点。用它代替逐级遍历可以显著省额度。响应体可能较大,建议开启 gzip。

批量查询

一次请求查多个代码,减少网络往返。按请求里传入的代码个数计费,这是唯一一个不按请求次数计费的接口。

POST/area/v1/regions/batch按代码个数计费
字段类型必填说明
codesarray<string>必填区划代码数组(2 / 4 / 6 / 9 / 12 位),1 到 100 个。按去重后的代码个数计费(44 与 440000000000 视为同一个)。
versionstring可选数据版本(年度),默认取当前版本 2024。
cURL一次查三个代码
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 位),方便定位上游脏数据。

HTTP 200POST /area/v1/regions/batch
{
  "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含义是否计费怎么处理
0200成功计费读取 data。
40001400参数错误不计费按 message 和 data.errors(字段级说明)修正参数,不要重试。
40101401缺少 API Key不计费检查是否带上了 X-API-Key 请求头。
40102401API Key 无效不计费确认 Key 是否复制完整、是否误用了已重置的旧 Key。
40103401API Key 已停用不计费在控制台恢复该 Key,或新建一个。
40201402无有效套餐不计费开通试用、充值或购买订阅(见 data.renew_url)。不要重试。
40202402额度已用尽不计费充值或升级套餐,即时恢复。不要重试。
40203402超出当日限额不计费次日零点重置,或换用不设日上限的套餐。
40301403IP 不在白名单不计费把服务器出口 IP 加进该 Key 的白名单。
40302403套餐不含该接口不计费升级到包含该接口的套餐。
40303403Key 不属于此项目不计费换用在本项目下创建的 Key。
40401404区划不存在不计费确认代码是否属于当前数据版本,历史撤并的代码可能已不存在。
42901429请求过于频繁不计费按响应头 Retry-After 退避后重试,或升级套餐提高 QPS。
50001 / 50301500 / 503服务端错误 / 暂不可用不计费稍后重试;持续出现请带上 request_id 联系技术支持。

错误响应示例

HTTP 402额度已用尽
{
  "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 数组列出未命中的代码。

准备好接入了

注册后开通免费试用,7 天 / 1,000 次,拿到 Key 就能跑上面的示例。