{"openapi":"3.0.3","info":{"title":"行政区划","description":"提供全国行政区划数据查询（省、市、区县）与智能地址解析服务。\n### 平台统一约定\n- **响应信封**：`output=json`（默认）返回 `{code, msg, data}`，code 与 HTTP 状态码一致；`output=raw` 直接返回简单文本或图片二进制\n- **鉴权**：公开接口无需凭据；需鉴权接口携带 `X-App-Id` + `X-App-Secret`（明文）或 `X-App-Id` + `X-Timestamp` + `X-Nonce` + `X-Signature`（HMAC-SHA256 签名），文档页右上角「鉴权助手」可在线生成请求头\n- **默认限流**：60 次/秒（粒度 {appid|ip}:{plugin}，appid 级配额可覆盖；超限返回 429）\n- **文档数据**：接口参数/返回/示例来自 handler 方法 PHPDoc 注解，方法注册/鉴权/限流来自 manifest","version":"1.0.0"},"servers":[{"url":"/api/area","description":"当前站点"}],"tags":[{"name":"公开接口","description":"无需凭据即可调用"},{"name":"需鉴权接口","description":"需携带 appid/appsecret（明文双头或 HMAC 签名），详见「鉴权助手」"}],"paths":{"/all":{"get":{"tags":["公开接口"],"summary":"返回省市区全量扁平列表","description":"**返回**：data 为扁平列表，每项 {name, level, adcode, parent_adcode, parent_name}（level: province|city|district）\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_all","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（每行一条记录）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":[{"name":"北京市","level":"province","adcode":"110000","parent_adcode":"","parent_name":""}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/tree":{"get":{"tags":["公开接口"],"summary":"返回省市区树形结构","description":"**返回**：data 为嵌套数组，省级节点 {name, adcode, districts:[{name, adcode, districts:[...]}]}\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_tree","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（每行一条记录）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":[{"name":"北京市","adcode":"110000","districts":[{"name":"东城区","adcode":"110101","districts":[]}]}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/provinces":{"get":{"tags":["公开接口"],"summary":"返回省份列表","description":"**返回**：data 为省级行政区列表，每项 {name, level, adcode, parent_adcode, parent_name}\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_provinces","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（每行一条记录）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":[{"name":"浙江省","level":"province","adcode":"330000","parent_adcode":"","parent_name":""}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/cities":{"get":{"tags":["公开接口"],"summary":"返回城市列表","description":"**返回**：data 为城市列表，每项 {name, level, adcode, parent_adcode, parent_name}（parent_* 为所属省）\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_cities","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（每行一条记录）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":[{"name":"杭州市","level":"city","adcode":"330100","parent_adcode":"330000","parent_name":"浙江省"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/districts":{"get":{"tags":["公开接口"],"summary":"返回区县列表","description":"**返回**：data 为区县列表，每项 {name, level, adcode, parent_adcode, parent_name}（parent_* 为所属市）\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_districts","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（每行一条记录）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":[{"name":"西湖区","level":"district","adcode":"330106","parent_adcode":"330100","parent_name":"杭州市"}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/smart":{"get":{"tags":["公开接口"],"summary":"智能解析地址字符串","description":"从一段自由文本中提取用户信息（姓名/电话/身份证号/邮编）、省市区行政区划（含 adcode/区号/中心坐标）与结构化街道明细。\n支持行政后缀省略（「广东深圳南山科技园」）、自治区简称（「广西南宁」）、县级市（「云南大理市下关镇」）、\n直筒子市乡镇（「东莞市虎门镇」）、错省错市纠错（「浙江省苏州市」→ 江苏省）、噪声前缀（「我家在」）、全角字符。\n\ndata 各字段含义：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| user.name | string | 收货人姓名；支持敬称剥离（「王大锤先生」→「王大锤」）、单字姓（「廖」，排除方位/数字/行政字）、单字姓+敬称（「廖先生」）、英文姓名（「Mr Smith」）；未识别为空 |\n| user.phone | string | 电话号码；识别手机号、400/800 客服号、区号座机，自动剥离 +86/0086 前缀；未识别为空 |\n| user.idcard | string | 18 位身份证号（末位 x 统一转大写）；未识别为空 |\n| user.postcode | string | 6 位邮政编码；仅识别独立成词的数字，避免吞并门牌号；未识别为空 |\n| address | string | 剥离用户信息后的纯地址文本（保留原始空格） |\n| region.province | object | 省级行政区，未命中时各子字段为空字符串 |\n| region.city | object | 市级行政区；直辖市返回「北京城区」「重庆郊县」等城区条目；未命中时为空 |\n| region.district | object | 区县级行政区；直筒子市（东莞/中山）与省直辖县级市无区县，为空，乡镇落在 detail.town |\n\nregion 内三级（province/city/district）为同构对象：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| name | string | 标准行政区划全名（如「浙江省」「杭州市」「西湖区」） |\n| adcode | string | 行政区划代码（国标 GB/T 2260，如 330106） |\n| citycode | string | 城市区号（如 0571），省级为空 |\n| center | string | 区域中心点经纬度，格式「经度,纬度」（高德坐标系） |\n\ndetail 街道结构化明细：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| full | string | 街道完整地址（去除省市区后的剩余原文，含镇/村/路/门牌等全部信息） |\n| town | string | 乡镇/街道名（如「虎门镇」「望京街道」「大良街道」），无法识别为空 |\n| village | string | 村/社区名（如「甲坝村」），无法识别为空 |\n| road | string | 道路名（如「文三路」「中关村大街」「民族大道」） |\n| house_number | string | 门牌号（如「138号」）；「3号楼」归入 building 不算门牌 |\n| building | string | 楼栋（如「10栋」「A座」「3号楼」「甲幢」），支持中文数字与字母 |\n| unit | string | 单元（如「一单元」「单元2」） |\n| floor | string | 楼层（如「5楼」「地下1层」） |\n| room | string | 房间号（如「502室」「3号房」） |\n| confidence | number | 解析置信度 0-1：三级区划全名命中≈0.9+，简称命中≈0.7-0.85，父级由子级反推或仅部分命中更低；可用作是否人工复核的阈值 |\n\n**返回**：data 为解析结果，字段含义见上方表格\n\n**默认限流**：60 次/秒（appid 级配额可覆盖）","operationId":"area_smart","x-auth-required":false,"x-rate-limit":{"s":60},"parameters":[{"name":"text","in":"query","required":true,"description":"待解析的地址文本（可含姓名/手机号/座机/身份证号/邮编，支持行政后缀省略、简称、全角字符，如：广东深圳南山 张三 13800138000）","schema":{"type":"string"}},{"name":"output","in":"query","required":false,"description":"json（默认，统一信封）|raw（字段按序空格拼接：name phone idcard postcode province city district street）","schema":{"type":"string"}}],"responses":{"200":{"description":"成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"},"example":{"code":200,"msg":"","data":{"user":{"name":"张三","phone":"13800138000","idcard":"","postcode":""},"address":"浙江省杭州市西湖区文三路138号","region":{"province":{"name":"浙江省","adcode":"330000","citycode":"","center":"120.155147,30.27408"},"city":{"name":"杭州市","adcode":"330100","citycode":"0571","center":"120.153576,30.287459"},"district":{"name":"西湖区","adcode":"330106","citycode":"0571","center":"120.130203,30.259324"}},"detail":{"full":"文三路138号","town":"","village":"","road":"文三路","house_number":"138号","building":"","unit":"","floor":"","room":""},"confidence":1}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"400":{"$ref":"#/components/responses/BadRequest"}}}}},"components":{"schemas":{"Envelope":{"type":"object","description":"平台统一响应信封，code 与 HTTP 状态码一致；output=raw 时无信封（直接输出文本/图片二进制）","properties":{"code":{"type":"integer","description":"200 成功；400 参数错误；401 凭据无效；403 拒绝访问；429 触发限流；500 服务异常"},"msg":{"type":"string","description":"提示信息"},"data":{"type":"object","description":"业务数据（结构见各接口说明）"}}}},"securitySchemes":{"plainAppId":{"type":"apiKey","in":"header","name":"X-App-Id","description":"明文方式：appid"},"plainSecret":{"type":"apiKey","in":"header","name":"X-App-Secret","description":"明文方式：appsecret（HTTPS 下使用）"},"hmacAppId":{"type":"apiKey","in":"header","name":"X-App-Id","description":"HMAC 方式：appid"},"hmacTimestamp":{"type":"apiKey","in":"header","name":"X-Timestamp","description":"HMAC 方式：秒级时间戳（±300s 时间窗）"},"hmacNonce":{"type":"apiKey","in":"header","name":"X-Nonce","description":"HMAC 方式：一次性随机串（5 分钟内不可重复）"},"hmacSignature":{"type":"apiKey","in":"header","name":"X-Signature","description":"HMAC 方式：base64(HMAC-SHA256(secret, 签名串))，签名串见「鉴权助手」"}},"responses":{"BadRequest":{"description":"参数错误（缺少必填/格式非法）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"Unauthorized":{"description":"凭据缺失或无效（appid 不存在/停用/未授权该插件/签名错误）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"Forbidden":{"description":"拒绝访问（IP/UA 名单命中）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"RateLimited":{"description":"触发限流（X-RateLimit-Remaining: 0，Retry-After 头提示等待秒数）","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"ServerError":{"description":"服务端异常","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}}}},"x-plugin":{"slug":"area","name":"行政区划","description":"提供全国行政区划数据查询（省、市、区县）与智能地址解析服务。","version":"1.0.0","methodCount":6,"authMethods":[],"rateLimit":{"s":60},"warnings":[]}}