查看全局 API 说明（请求/响应头、通用 JSON 格式）

邮政编码 API

地名查邮编、邮编查地名，覆盖区县一级行政区划

Base URL https://www.resapi.cn/v1/zipcode

简介

基于本地邮编库（约 2800 条区县记录）支持双向查询；可按区县名、省市区全称、拼音模糊搜索。数据仅供参考，请以邮政部门最新公布为准。

GET /v1/zipcode/lookup

根据 6 位邮政编码 查询对应地名（省、市、区县及行政区划代码）。

同一邮编可能对应多个区县；仅支持 6 位数字邮编精确匹配。数据来源于本地静态库，仅供参考。

查询参数

名称	类型	必填	说明	示例
zip	string	是	6 位邮政编码	`100020`

响应字段

data 为数组，每项：

字段	说明
adcode	6 位行政区划代码
name	区县名称
province / city	省、市
province_code / city_code	省级、市级代码
zip_code	邮政编码
pinyin	拼音（空格分隔）
full_name	组合全称，如「北京市朝阳区」

meta.zip / meta.count / meta.note 为辅助信息。

响应示例

{
  "data": [
    {
      "adcode": "110105",
      "name": "朝阳区",
      "province_code": "11",
      "city_code": "1101",
      "province": "北京市",
      "city": "北京市",
      "zip_code": "100020",
      "pinyin": "chao yang",
      "full_name": "北京市朝阳区"
    }
  ],
  "meta": {
    "zip": "100020",
    "count": 1,
    "note": "同一邮编可能对应多个区县；数据仅供参考，请以邮政部门最新公布为准"
  }
}

GET /v1/zipcode/search

根据 地名关键词 模糊查询邮编（支持区县名、省市区全称、拼音等）。

查询参数

名称	类型	必填	说明	示例
q	string	是	搜索关键词	`朝阳区`
limit	int	否	返回条数，默认 20，最大 100	`10`

响应字段

data 结构与 /lookup 相同；meta.q / meta.count / meta.limit 为查询摘要。

响应示例

{
  "data": [
    {
      "adcode": "110105",
      "name": "朝阳区",
      "province": "北京市",
      "city": "北京市",
      "zip_code": "100020",
      "full_name": "北京市朝阳区"
    },
    {
      "adcode": "220104",
      "name": "朝阳区",
      "province": "吉林省",
      "city": "长春市",
      "zip_code": "130012",
      "full_name": "吉林省长春市朝阳区"
    }
  ],
  "meta": {
    "q": "朝阳区",
    "count": 2,
    "limit": 20
  }
}

通用错误码

以下错误码适用于平台全部 /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	参数无效	`zip` 非 6 位数字、`q` 为空等
404	not_found	未找到	邮编在库中无匹配记录

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

邮编查地名

GET /v1/zipcode/lookup?zip=100020

cURL

curl -s "https://www.resapi.cn/v1/zipcode/lookup?zip=100020" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/zipcode/lookup?zip=100020", {
  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/zipcode/lookup",
    params={"zip": "100020"},
    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/zipcode/lookup?zip=100020"
  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

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/zipcode/lookup?zip=100020";
    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/zipcode/lookup?zip=100020";
$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/zipcode/lookup?zip=100020");
Console.WriteLine(json);

地名查邮编

GET /v1/zipcode/search?q=朝阳区&limit=10

cURL

curl -s "https://www.resapi.cn/v1/zipcode/search?q=%E6%9C%9D%E9%98%B3%E5%8C%BA&limit=10" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/zipcode/search?q=朝阳区&limit=10", {
  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/zipcode/search",
    params={"q": "朝阳区", "limit": 10},
    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/zipcode/search?q=朝阳区&limit=10"
  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

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/zipcode/search?q=朝阳区&limit=10";
    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/zipcode/search?q=" . urlencode("朝阳区") . "&limit=10";
$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/zipcode/search?q=朝阳区&limit=10");
Console.WriteLine(json);