免费注册 用户登录

行政区划查询 API（region.query）

按行政区划代码、名称、拼音、邮编或省市名称，查询中国省 / 市 / 区县三级数据及邮政编码。 接口编码 region.query，仅需请求头携带 X-API-Key，无需签名、时间戳或加密。

0.0100 元/次 GET JSON / UTF-8 免签名 平均 20ms 每周更新

当前收费方式：PER_CALL（按次计费，0.0100 元/次）（后台「接口管理」可随时调整）

最后更新： · 接口版本 v1

接口概述

一句话说明

region.query 是 XAPI 提供的行政区划数据查询接口，返回省 / 市 / 区县三级名称、 行政区划代码（Adcode）与邮政编码。 数据源为国家统计局行政区划代码与邮政编码整理数据， 每周日凌晨全量同步一次（新增 → 插入，变更 → 更新，源数据中移除 → 逻辑删除）， 可安全用于地址解析、三级联动、邮编填充等场景。

接口规格
请求地址 https://api.xujian.tech/openapi/region/query
请求方式 GET
鉴权方式 请求头 X-API-Key（不做签名与加密）
接口编码 region.query
收费类型 PER_CALL（按次计费，0.0100 元/次）
响应格式 JSON，Content-Type: application/json;charset=UTF-8
是否需要授权 否（无需授权，API Key 有效且余额充足即可调用）
数据更新频率 每周日 03:00 全量同步，支持管理端手动触发
典型用途 省市区三级联动、地址解析与标准化、邮政编码填充、行政区划代码转换、报表区域归类

快速开始

把 你的APIKey 换成控制台获取的 API Key，按行政区划代码精确查询：

cURL 
curl -s "https://api.xujian.tech/openapi/region/query?code=110101" \
  -H "X-API-Key: 你的APIKey"

查询全部省份（level=1）

cURL 
curl -s "https://api.xujian.tech/openapi/region/query?level=1&limit=100" \
  -H "X-API-Key: 你的APIKey"

查某省的全部地市（只传 province）

cURL 
curl -s "https://api.xujian.tech/openapi/region/query?province=%E6%B5%99%E6%B1%9F%E7%9C%81&limit=100" \
  -H "X-API-Key: 你的APIKey"

查某市的全部区县（传 city）

cURL 
curl -s "https://api.xujian.tech/openapi/region/query?province=%E6%B5%99%E6%B1%9F%E7%9C%81&city=%E6%9D%AD%E5%B7%9E%E5%B8%82&limit=100" \
  -H "X-API-Key: 你的APIKey"

三级联动推荐调用顺序

  1. level=1&limit=100 → 全部省份（约 34 条，code 为 6 位省级代码，如 110000 北京市）
  2. province=浙江省（不传 level） → 该省全部地市，level 返回 2
  3. province=浙江省&city=杭州市 → 该市全部区县，level 返回 3

第二、三步为接口的自动下钻行为：只要没有传 code / keyword / zipCode / level， 传 province 即返回地市、传 city 即返回区县；如需跳过下钻取其自身明细，显式传 level=3。

请求参数

请求头（Header）
参数名 类型 必填 说明
X-API-Key String 是 开发者 API Key，在控制台创建后获取；缺失或无效会返回失败
Query 参数（至少填写一个查询条件）
参数名 类型 必填 示例 说明
code String 否 110101 行政区划代码精确查询（区县级 6 位，省直辖县级 9 位）
keyword String 否 朝阳 名称 / 城市 / 省份 / 拼音模糊匹配
province String 否 浙江省 省份名称精确匹配。仅传 province（不带 code / keyword / zipCode / city / level）时， 返回该省下的全部地市（level=2），如浙江省 → 杭州市、宁波市……
city String 否 杭州市 城市名称精确匹配。传了 city（不带 code / keyword / zipCode / level）时， 返回该市下的全部区县（level=3），如杭州市 → 上城区、拱墅区…… 可与 province 组合以限定省份
zipCode String 否 100010 邮政编码精确匹配
level Integer 否 1 层级过滤，优先级最高：1 返回全部省级列表（去重，约 34 条，可直接作为三级联动第一级）； 2 返回地市级列表（去重，配合 province 可限定某省的地市）； 3 返回区县明细（可与 province / city 等任意条件组合）。 不传 level 时由接口按下钻规则自动判定：只传 province → 地市，传了 city → 区县
limit Integer 否 20 返回条数，默认 20，最大 100（查全部省份请用 limit=100）

响应参数

顶层字段
字段 类型 说明
code int 状态码，0 表示成功，非 0 表示失败（常见为 500）
msg String 结果描述，成功为 success，失败为具体原因
data Object 业务数据，失败时为 null
data 字段
字段 类型 示例 说明
total Integer 1 本次返回的记录条数
list Array [{...}] 行政区划记录列表，字段见下表
apiCode String region.query 接口编码
apiName String 行政区划查询 接口名称
chargeType String PER_CALL 计费类型：FREE 免费 / PER_CALL 按次 / MONTHLY 按月 / YEARLY 按年（本接口后台配置为 PER_CALL）
balance BigDecimal 100.0000 调用完成后（已扣费）的账户余额（元）
costMs Long 5 本次调用耗时（毫秒）
list[] 元素字段（仅返回下列字段，不含 status / syncTime / createTime / updateTime / deleted 等内部字段）
字段 类型 示例 说明
code String 110101 行政区划代码
name String 东城区 区县名称
city String 北京市 地级市名称
cityCode String 1101 地级市代码
province String 北京市 省级名称
provinceCode String 11 省级代码
zipCode String 100010 邮政编码
pinyin String dong cheng 区县名称拼音
level Integer 3 层级：1 省 / 2 市 / 3 区县

响应示例

成功（code = 0）—— 按代码查区县明细

JSON 
{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 1,
    "list": [
      {
        "code": "110101",
        "name": "东城区",
        "cityCode": "1101",
        "city": "北京市",
        "provinceCode": "11",
        "province": "北京市",
        "zipCode": "100010",
        "pinyin": "dong cheng",
        "level": 3
      }
    ],
    "apiCode": "region.query",
    "apiName": "行政区划查询",
    "chargeType": "PER_CALL",
    "balance": 100.0000,
    "costMs": 5
  }
}

成功（code = 0）—— province=浙江省，返回该省全部地市

JSON 
{
  "code": 0,
  "msg": "success",
  "data": {
    "total": 11,
    "list": [
      {
        "code": "330100",
        "name": "杭州市",
        "cityCode": "3301",
        "city": "杭州市",
        "provinceCode": "33",
        "province": "浙江省",
        "zipCode": "",
        "pinyin": "",
        "level": 2
      },
      {
        "code": "330200",
        "name": "宁波市",
        "cityCode": "3302",
        "city": "宁波市",
        "provinceCode": "33",
        "province": "浙江省",
        "zipCode": "",
        "pinyin": "",
        "level": 2
      }
    ],
    "apiCode": "region.query",
    "apiName": "行政区划查询",
    "chargeType": "FREE",
    "balance": 100.0000,
    "costMs": 6
  }
}

地市级与省级为聚合结果：zipCode / pinyin 返回空字符串（邮编与拼音只在区县级明细上有值）， code 分别补位为 6 位市级 / 省级代码。

失败（未传查询条件）

JSON 
{
  "code": 500,
  "msg": "code / keyword / province / city / zipCode / level 至少填写一个查询条件",
  "data": null
}

错误码与常见失败原因

code msg（示例） 处理建议
0 success 调用成功
500 缺少请求头 X-API-Key 在请求头中补充 X-API-Key
500 API Key 无效 / API Key 已停用 检查 Key 是否正确，或在控制台重新启用
500 客户不存在或已停用 联系平台运营确认账号状态（可联系微信xujian_cq）
500 接口不存在或已停用 确认接口编码 region.query 当前是否维护中
500 余额不足，请先充值。可联系微信xujian_cq 按次计费接口在调用前校验余额，余额不足时不扣费，充值后重试（可联系微信xujian_cq）
500 code / keyword / province / city / zipCode / level 至少填写一个查询条件 补充至少一个查询条件后重试（查全部省份请传 level=1）
500 level 取值只能是 1 省 / 2 市 / 3 区县 level 只能传 1、2、3

多语言代码示例

Java（Hutool）

Java 
String body = HttpRequest.get("https://api.xujian.tech/openapi/region/query")
        .form("keyword", "朝阳")
        .form("province", "北京市")
        .form("limit", 10)
        .header("X-API-Key", apiKey)
        .timeout(5000)
        .execute()
        .body();

JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") == 0) {
    JSONArray list = json.getJSONObject("data").getJSONArray("list");
    list.forEach(o -> {
        JSONObject item = (JSONObject) o;
        System.out.println(item.getStr("code") + " " + item.getStr("province")
                + item.getStr("city") + item.getStr("name") + " " + item.getStr("zipCode"));
    });
}

Python

Python 
import requests

resp = requests.get(
    "https://api.xujian.tech/openapi/region/query",
    params={"code": "110101"},
    headers={"X-API-Key": API_KEY},
    timeout=5,
)
data = resp.json()
if data["code"] == 0:
    for item in data["data"]["list"]:
        print(item["province"], item["city"], item["name"], item["zipCode"])

JavaScript（浏览器 / Node 18+）

JavaScript 
const url = new URL("https://api.xujian.tech/openapi/region/query");
url.searchParams.set("keyword", "朝阳");
url.searchParams.set("limit", 20);

const resp = await fetch(url, { headers: { "X-API-Key": API_KEY } });
const { code, data } = await resp.json();
if (code === 0) {
  data.list.forEach((r) => console.log(r.code, r.province, r.city, r.name, r.zipCode));
}

常见问题（FAQ）

region.query 接口怎么收费？

region.query 的收费类型为 PER_CALL（按次计费），当前单价 0.0100 元/次，调用前校验余额，余额不足返回「余额不足，请先充值。可联系微信xujian_cq」且不扣费；充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。

有调用次数或频率限制吗？

当前版本不限制调用次数、不做硬性限流。请按业务需要合理调用；由于行政区划数据每周才更新一次， 强烈建议在本地缓存结果，避免重复请求。

怎么一次性拿到全部省份？

请求 level=1&limit=100，一次返回全部省级去重记录（约 34 条，含省 / 自治区 / 直辖市 / 特别行政区）。 由于源数据本身只有区县级明细行，省级与地市级列表由接口实时聚合生成。

三级联动推荐顺序：level=1 取省 → 只传 province=浙江省 取该省全部地市 → 再传 province=浙江省&city=杭州市 取该市全部区县。

传入 province 或 city 会返回什么？

接口会自动向下钻一级：

  • 只传 province（不带 code / keyword / zipCode / level）→ 返回该省全部地市，level=2；
  • 传了 city（不加上述条件）→ 返回该市全部区县，level=3；
  • 若希望跳过下钻、按条件精确检索区县级明细，请显式传 level=3，或改用 code / keyword / zipCode 查询。
行政区划数据多久更新一次？

每周日凌晨 03:00 自动全量同步一次，管理端也支持手动立即同步。同步采用「新增 / 更新 / 逻辑删除」的比对策略， 已下线地区会被标记为删除而不再返回，不会被物理删除。

可以一次查到多少条数据？

单次最多返回 100 条（limit 参数，默认 20）。需要全量数据建议按 province / city 分批拉取，并在本地缓存， 行政区划数据变更频率很低。

返回结果中的 code 和 zipCode 分别是什么？

code 是国家统计局行政区划代码（区县为 6 位，省直辖县级行政区为 9 位，如 419001000 济源市）， zipCode 是对应地区的邮政编码。

调用需要签名或加密吗？

不需要。XAPI 的接口仅校验请求头 X-API-Key，不做签名、时间戳或加密。

不传任何查询条件可以调用吗？

不可以。code、keyword、province、city、zipCode、level 至少需要提供一个， 否则返回「code / keyword / province / city / zipCode / level 至少填写一个查询条件」。

扫码添加微信
联系作者 · 微信二维码

微信号：xujian_cq

接口对接、充值 / 授权、定制需求都可以直接聊