全国行政区划 API

通用错误码

以下错误码适用于平台全部 /v1/* 接口（各接口在「错误代码」Tab 中另有本接口补充说明）。

错误响应格式

HTTP 状态码非 2xx 时，响应体一般为：

{
  "error": {
    "code": "错误码",
    "message": "错误信息"
  }
}

错误码一览

HTTP	code	message	说明
400	invalid_params	参数无效	必填参数缺失、格式不合法或超出允许范围
404	not_found	资源不存在	按编码或 ID 查询时无匹配记录
429	rate_limit_exceeded	请求过于频繁	超过当前 IP 的访问频率限制
500	internal_error	服务器内部错误	服务端或数据库异常，请稍后重试

限流、缓存等 HTTP 响应头含义见上文「响应头说明」。

---

本接口补充

HTTP	code	message	说明
400	invalid_params	参数无效	level 非法、q 为空、page/page_size 超范围、children 缺少 parent_code 等
404	not_found	资源不存在	按 code 或 ancestors 查询无匹配；children 的 parent_code 不存在

请求根地址为 https://www.resapi.cn。每个场景含 7 种语言（cURL → JavaScript → Python → Go → Java → PHP → C#）。

---

全国省份列表

GET /v1/regions/provinces?page_size=50

cURL

curl -s "https://www.resapi.cn/v1/regions/provinces?page_size=50" \
  -H "Accept: application/json"

---

列表筛选（查北京市下属 city）

GET /v1/regions?level=city&parent_code=110000&page_size=20

cURL

curl -s "https://www.resapi.cn/v1/regions?level=city&parent_code=110000&page_size=20" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/regions");
url.searchParams.set("level", "city");
url.searchParams.set("parent_code", "110000");
url.searchParams.set("page_size", "20");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/regions",
    params={"level": "city", "parent_code": "110000", "page_size": 20},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

func main() {
	url := "https://www.resapi.cn/v1/regions?level=city&parent_code=110000&page_size=20"
	req, _ := http.NewRequest(http.MethodGet, url, nil)
	req.Header.Set("Accept", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	var out map[string]any
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", out)
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        String url = "https://www.resapi.cn/v1/regions?level=city&parent_code=110000&page_size=20";
        HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Accept", "application/json")
            .GET()
            .build();
        HttpResponse<String> res = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(res.body());
    }
}

PHP

<?php
$url = "https://www.resapi.cn/v1/regions?level=city&parent_code=110000&page_size=20";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));
var json = await client.GetStringAsync("https://www.resapi.cn/v1/regions?level=city&parent_code=110000&page_size=20");
Console.WriteLine(json);

---

详情查询（按 code）

GET /v1/regions/110101

cURL

curl -s "https://www.resapi.cn/v1/regions/110101" -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/regions/110101", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

r = requests.get(
    "https://www.resapi.cn/v1/regions/110101",
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/regions/110101"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/regions/110101";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/regions/110101";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

var json = await client.GetStringAsync("https://www.resapi.cn/v1/regions/110101");
Console.WriteLine(json);

---

层级路径（ancestors）

GET /v1/regions/110108/ancestors

cURL

curl -s "https://www.resapi.cn/v1/regions/110108/ancestors" \
  -H "Accept: application/json"

---

同名地名检索（村名）

全国检索叫「火楼村」的行政村数量与列表：

GET /v1/regions/search?q=火楼村&level=village

仅在山东省检索：

GET /v1/regions/search?q=火楼村&level=village&province=山东省

响应 meta.total 为命中总数；用 page、page_size 翻页，meta.total_pages 为总页数。

cURL

curl -s "https://www.resapi.cn/v1/regions/search?q=%E7%81%AB%E6%A5%BC%E6%9D%91&level=village&page=1&page_size=10" \
  -H "Accept: application/json"

---

子级级联（北京市下辖区）

GET /v1/regions/children?parent_code=110000&page_size=20

cURL

curl -s "https://www.resapi.cn/v1/regions/children?parent_code=110000&page_size=20" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/regions/children");
url.searchParams.set("parent_code", "110000");
url.searchParams.set("page_size", "20");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/regions/children",
    params={"parent_code": "110000", "page_size": 20},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/regions/children?parent_code=110000&page_size=20"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/regions/children?parent_code=110000&page_size=20";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/regions/children?parent_code=110000&page_size=20";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
print_r(json_decode(file_get_contents($url, false, $ctx), true));

C#

var json = await client.GetStringAsync(
    "https://www.resapi.cn/v1/regions/children?parent_code=110000&page_size=20");
Console.WriteLine(json);

---

关键词搜索

GET /v1/regions/search?q=海淀&level=district&limit=20

cURL

curl -s "https://www.resapi.cn/v1/regions/search?q=%E6%B5%B7%E6%B7%80&level=district&limit=20" \
  -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/regions/search");
url.searchParams.set("q", "海淀");
url.searchParams.set("level", "district");
url.searchParams.set("limit", "20");
const res = await fetch(url, { headers: { Accept: "application/json" } });
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

r = requests.get(
    "https://www.resapi.cn/v1/regions/search",
    params={"q": "海淀", "level": "district", "limit": 20},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/regions/search?q=%E6%B5%B7%E6%B7%80&level=district&limit=20"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/regions/search?q=%E6%B5%B7%E6%B7%80&level=district&limit=20";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/regions/search?q=%E6%B5%B7%E6%B7%80&level=district&limit=20";
$ctx = stream_context_create([
    "http" => ["header" => "Accept: application/json\r\n"],
]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

var json = await client.GetStringAsync("https://www.resapi.cn/v1/regions/search?q=%E6%B5%B7%E6%B7%80&level=district&limit=20");
Console.WriteLine(json);