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

地址标准化 API

提供地址建议、地址解析与行政区划标准化

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

简介

基于全国行政区划数据，解析与标准化省/市/区，并返回标准 region_code，可与区划 API 联动。

GET /v1/address/suggest

地址候选建议（用于输入联想）。

查询参数

名称	类型	必填	说明	示例
q	string	是	关键词（名称/编码/路径）	海淀
limit	int	否	返回条数，默认 20，最大 100	20

GET /v1/address/parse

将自由文本地址拆解为省/市/区和剩余详细地址，并返回标准区划编码。

查询参数

名称	类型	必填	说明	示例
text	string	是	原始地址文本	北京市海淀区中关村大街27号

响应字段

字段	说明
region_code	已识别区划中最细粒度的标准编码（通常为 `district`；仅识别到省时为省级编码）
parsed.province / city / district	各级区划对象，含 `code`、`name`、`level` 等
detail	去除省市区后的详细地址

响应示例

{
  "data": {
    "input": "北京市海淀区中关村大街27号",
    "region_code": "110108",
    "parsed": {
      "province": { "code": "110000", "name": "北京市", "level": "province" },
      "city": { "code": "110100", "name": "市辖区", "level": "city" },
      "district": { "code": "110108", "name": "海淀区", "level": "district" }
    },
    "detail": "中关村大街27号"
  }
}

GET /v1/address/normalize

标准化省市区并拼接完整地址，返回各级编码与标准区划编码。

查询参数

名称	类型	必填	说明	示例
province	string	是	省级名称	北京市
city	string	是	市级名称	市辖区
district	string	是	区县名称	海淀区
detail	string	否	详细地址	中关村大街27号

响应字段

字段	说明
region_code	区县编码（与 `district.code` 一致）
province / city / district	标准化后的区划对象
full_address	拼接后的完整地址

响应示例

{
  "data": {
    "region_code": "110108",
    "province": { "code": "110000", "name": "北京市", "level": "province" },
    "city": { "code": "110100", "name": "市辖区", "level": "city" },
    "district": { "code": "110108", "name": "海淀区", "level": "district" },
    "detail": "中关村大街27号",
    "full_address": "北京市市辖区海淀区中关村大街27号"
  }
}

通用错误码

以下错误码适用于平台全部 /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	参数无效	q、text 为空，或省市区参数不匹配

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

地址建议

GET /v1/address/suggest?q=海淀&limit=10

cURL

curl -s "https://www.resapi.cn/v1/address/suggest?q=%E6%B5%B7%E6%B7%80&limit=10" -H "Accept: application/json"

JavaScript

const url = new URL("https://www.resapi.cn/v1/address/suggest");
url.searchParams.set("q", "海淀");
url.searchParams.set("limit", "10");
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/address/suggest",
    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/address/suggest?q=%E6%B5%B7%E6%B7%80&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/address/suggest?q=%E6%B5%B7%E6%B7%80&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/address/suggest?q=%E6%B5%B7%E6%B7%80&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/address/suggest?q=%E6%B5%B7%E6%B7%80&limit=10");
Console.WriteLine(json);

地址解析

GET /v1/address/parse?text=北京市海淀区中关村大街27号

响应 data.region_code 为最细已识别区划编码（本例为海淀区 110108）。

cURL

curl -s "https://www.resapi.cn/v1/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7" -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7", {
  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/address/parse",
    params={"text": "北京市海淀区中关村大街27号"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7"
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/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7";
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/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7";
$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/address/parse?text=%E5%8C%97%E4%BA%AC%E5%B8%82%E6%B5%B7%E6%B7%80%E5%8C%BA%E4%B8%AD%E5%85%B3%E6%9D%91%E5%A4%A7%E8%A1%9727%E5%8F%B7");
Console.WriteLine(json);