城市天气ID查询

# 城市天气ID查询API接口文档 (v1) ## 接口概述 城市天气ID查询API是一个本地数据查询接口，从本地城市数据库中查找对应的城市天气ID及相关地理信息。支持精确匹配、完整路径匹配、简称匹配、拼音模糊搜索，以及上级地区自动返回下级全部数据的智能查询策略。 数据来源于本地 `csid.json`（3749条全国城市数据），无需依赖任何第三方API服务，稳定可靠。 ## 接口地址 ``` GET/POST https://api.xunjinlu.fun/api/weather/csid.php ``` ## 请求方式 - `GET` - 通过URL参数传递 - `POST` - 通过表单格式传递 ## 请求参数 ### 参数说明 | 参数名 | 类型 | 必填 | 说明 | |--------|------|------|------| | city | string | 是 | 城市名称、行政区名称、完整地区路径（如 `中国,北京,北京市,朝阳区`）、拼音（如 `Beijing`）、天气ID（如 `101010100`）或行政区划编码 | ### JSON 请求参数示例 ```json [ { "name": "city", "type": "string", "required": true, "description": "城市名称、行政区名称、完整地区路径、拼音、天气ID或行政区划编码。支持精确匹配与模糊搜索。", "example": "北京" } ] ``` #### 请求示例 **按省份名称查询（返回该省所有下级）：** ``` GET ?city=北京 GET ?city=上海 GET ?city=广东省 ``` **按城市名称查询（返回精确结果）：** ``` GET ?city=北京市 GET ?city=深圳市 ``` **按完整路径查询：** ``` GET ?city=中国,北京,北京市 GET ?city=中国,广东省,广州市,天河区 ``` **按区县名称查询：** ``` GET ?city=朝阳区 GET ?city=东城区 ``` **按拼音查询：** ``` GET ?city=Beijing GET ?city=Chaoyang ``` **按天气ID查询：** ``` GET ?city=101010100 ``` ## 查询策略说明 接口采用三级智能匹配策略，按优先级从高到低执行： | 优先级 | 匹配类型 | 说明 | |--------|----------|------| | 1 | 精确匹配（Subtree） | 输入与 `full_name` 或 `name` 完全一致，且命中省份（`city_lv=1`）或名称与简称一致时，返回该地区及其所有下级数据 | | 2 | 精确匹配（Exact） | 输入与 `full_name` 或 `name` 完全一致，仅返回精确命中的记录 | | 3 | 模糊匹配（Fuzzy） | 输入包含在 `full_name`、`name`、`short_name`、`city_name`、`pin_yin`、`city_code`、`area_code` 任一字段中，返回所有匹配结果 | ### city_lv 层级说明 | 层级值 | 含义 | |--------|------| | 1 | 省/直辖市/自治区 | | 2 | 市 | | 3 | 区/县 | ### 智能展开规则 - 用户输入**省级名称**（如 `北京`、`广东省`）→ 自动返回该省下**所有市、区县**的完整数据 - 用户输入**市级名称**且与简称一致（如输入 `石家庄`，名称简称为 `石家庄` 但 `name` 为 `石家庄市`）→ 自动返回该市下**所有区县**的完整数据 - 用户输入**区县级精确名称**（如 `朝阳区`）→ 仅返回精确匹配的朝阳区记录 ## 响应参数 ### 成功响应（Subtree - 返回下级全部数据） 用户输入 `北京`，命中省级（`city_lv=1`），返回北京下全部18个地区： ```json { "code": 200, "message": "success", "data": { "success": true, "type": "subtree", "match_level": "exact_parent", "input": "北京", "count": 18, "results": [ { "id": 1, "pid": 0, "area_code": 110000, "name": "北京", "parent_id": 100000, "short_name": "北京", "city_lv": 1, "tel_code": "", "post_code": null, "full_name": "中国,北京", "lng": 116.405285, "lat": 39.904989, "pin_yin": "Beijing", "city_code": "101010100", "city_name": "北京", "ctime": null }, { "id": 2, "pid": 1, "area_code": 110100, "name": "北京市", "parent_id": 110000, "short_name": "北京", "city_lv": 2, "tel_code": "10", "post_code": "100000", "full_name": "中国,北京,北京市", "lng": 116.405285, "lat": 39.904989, "pin_yin": "Beijing", "city_code": "101010100", "city_name": "北京", "ctime": null }, { "id": 3, "pid": 2, "area_code": 110101, "name": "东城区", "parent_id": 110100, "short_name": "东城", "city_lv": 3, "tel_code": "010", "post_code": "100010", "full_name": "中国,北京,北京市,东城区", "lng": 116.41005, "lat": 39.93157, "pin_yin": "Dongcheng", "city_code": "101010100", "city_name": "东城", "ctime": null } ] }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 成功响应（Exact - 精确匹配单条） 用户输入 `北京市` 或 `中国,北京,北京市`，精确命中市级： ```json { "code": 200, "message": "success", "data": { "success": true, "type": "exact", "match_level": "exact_name_or_full_name", "input": "北京市", "count": 1, "results": [ { "id": 2, "pid": 1, "area_code": 110100, "name": "北京市", "parent_id": 110000, "short_name": "北京", "city_lv": 2, "tel_code": "10", "post_code": "100000", "full_name": "中国,北京,北京市", "lng": 116.405285, "lat": 39.904989, "pin_yin": "Beijing", "city_code": "101010100", "city_name": "北京", "ctime": null } ] }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 成功响应（Fuzzy - 模糊匹配多条） 用户输入 `朝阳`，模糊匹配到北京朝阳区和长春朝阳区： ```json { "code": 200, "message": "success", "data": { "success": true, "type": "fuzzy", "match_level": "contains", "input": "朝阳", "count": 2, "results": [ { "id": 5, "pid": 2, "area_code": 110105, "name": "朝阳区", "parent_id": 110100, "short_name": "朝阳", "city_lv": 3, "tel_code": "10", "post_code": "100020", "full_name": "中国,北京,北京市,朝阳区", "lng": 116.48548, "lat": 39.9484, "pin_yin": "Chaoyang", "city_code": "101010300", "city_name": "朝阳", "ctime": null }, { "id": 261, "pid": 260, "area_code": 220104, "name": "朝阳区", "parent_id": 220100, "short_name": "朝阳", "city_lv": 3, "tel_code": "431", "post_code": "130012", "full_name": "中国,吉林省,长春市,朝阳区", "lng": 125.28831, "lat": 43.83339, "pin_yin": "Chaoyang", "city_code": "101060101", "city_name": "朝阳", "ctime": null } ] }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 错误响应（缺少参数） ```json { "code": 400, "message": "缺少必要参数: city", "data": { "tip": "请传入城市名称、行政区名称、完整地区路径、拼音、天气ID或行政区划编码", "example": "?city=北京 或 ?city=北京市 或 ?city=中国,北京,北京市 或 ?city=朝阳区" }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 错误响应（未找到匹配） ```json { "code": 404, "message": "未找到匹配的城市", "data": { "input": "火星市", "tip": "请检查城市名称是否正确，可尝试输入省、市、区县名称或完整地区路径" }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 错误响应（服务器错误） ```json { "code": 500, "message": "本地城市数据文件不存在: csid.json", "data": null, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ## 响应字段说明 ### 顶层字段 | 字段 | 类型 | 说明 | |------|------|------| | code | int | 状态码，200为成功，400为参数错误，404为未找到，500为服务器错误 | | message | string | 状态描述信息 | | data | object/null | 查询结果数据，失败时为错误提示信息 | | time | string | 服务器响应时间，格式 `YYYY-MM-DD HH:MM:SS` | | api_info | object | API开发者信息 | ### data 字段（成功时） | 字段 | 类型 | 说明 | |------|------|------| | data.success | bool | 查询是否成功 | | data.type | string | 匹配类型：`subtree`（子树返回）、`exact`（精确匹配）、`fuzzy`（模糊匹配） | | data.match_level | string | 匹配级别：`exact_parent`（命中上级）、`exact_name_or_full_name`（精确命中）、`contains`（模糊包含） | | data.input | string | 用户输入的原始查询关键词 | | data.count | int | 返回结果数量 | | data.results | array | 城市数据记录数组 | ### data.results[] 字段（每条城市记录） | 字段 | 类型 | 说明 | |------|------|------| | id | int | 城市数据唯一标识ID | | pid | int | 父级城市ID，顶层省份的 pid 为 0 | | area_code | int/string | 行政区划编码（6位数字） | | name | string | 城市当前层级名称（如 `北京市`、`朝阳区`） | | parent_id | int | 上级行政区划编码 | | short_name | string | 城市简称（如 `北京`、`朝阳`） | | city_lv | int | 城市层级：1=省，2=市，3=区/县 | | tel_code | string | 电话区号（如 `010`、`311`） | | post_code | string/null | 邮政编码 | | full_name | string | 完整地区路径（如 `中国,北京,北京市,朝阳区`） | | lng | float | 经度坐标 | | lat | float | 纬度坐标 | | pin_yin | string | 城市拼音（如 `Beijing`、`Chaoyang`） | | city_code | string | 天气城市代码（9位数字，用于天气接口查询） | | city_name | string | 城市天气名称（如 `北京`、`朝阳`） | | ctime | string/null | 创建时间 | ### api_info 字段 | 字段 | 类型 | 说明 | |------|------|------| | api_info.developer | string | 开发者名称 | | api_info.blog | string | 开发者博客地址 | | api_info.api_platform | string | API平台地址 | ## 数据统计 | 指标 | 数值 | |------|------| | 数据总量 | 3749 条 | | 覆盖范围 | 全国省/市/区县三级行政区划 | | 数据来源 | 本地 csid.json，定时更新 | | 数据格式 | JSON | ## 注意事项 1. **跨域支持**：接口已配置CORS，支持 `*` 跨域访问 2. **本地数据**：所有数据均来自本地 JSON 文件，不依赖任何第三方API，稳定可靠 3. **智能匹配**：接口自动判断用户输入是省份、城市还是区县，智能返回对应范围的数据 4. **模糊搜索**：支持拼音、电话区号、天气ID等多字段模糊搜索，搜索结果自动去重 5. **编码格式**：接口返回 UTF-8 编码的 JSON 数据，中文不会转义为 Unicode 6. **请求方式**：同时支持 GET 和 POST 请求 7. **自动去重**：当多个城市同名时（如北京朝阳区和长春朝阳区），模糊搜索不会重复返回 ## 典型查询场景对照表 | 用户输入 | 匹配方式 | 返回数量 | 说明 | |----------|----------|----------|------| | `北京` | Subtree（省级展开） | 18 | 命中省级（city_lv=1），返回全省 | | `北京市` | Exact（精确命中） | 1 | 精确命中市级（city_lv=2） | | `中国,北京,北京市` | Exact（精确命中） | 1 | 完整路径精确命中 | | `朝阳区` | Exact（精确命中） | 1 | 精确命中区县级（city_lv=3），不展开 | | `朝阳` | Fuzzy（模糊搜索） | 2 | 返回北京朝阳区+长春朝阳区 | | `上海` | Subtree（省级展开） | 19 | 命中省级，返回全市各区 | | `广东省` | Subtree（省级展开） | 若干 | 命中省级，返回全省各市各区 | | `101010100` | Fuzzy（模糊搜索） | 若干 | 按天气ID模糊匹配 | | `Beijing` | Fuzzy（拼音搜索） | 若干 | 按拼音模糊匹配 | | `010` | Fuzzy（区号搜索） | 若干 | 按电话区号模糊匹配 | ## 更新日志 | 版本 | 日期 | 说明 | |------|------|------| | v2.0.0 | 2026-05-23 | 全面升级为本地数据直读，新增智能模糊搜索，支持16个完整字段返回 | ## 开发者信息 - **开发者**：尋鯨錄 - **博客**：[https://www.xunjinlu.fun](https://www.xunjinlu.fun) - **API平台**：[https://api.xunjinlu.fun](https://api.xunjinlu.fun)

> **由 AI 生成**：本接口文档由 AI 根据配置自动生成，仅供参考，实际接口行为以服务端返回为准。 ## 接口简介 本接口用于根据城市名称查询对应的天气城市ID，支持模糊匹配，返回所有匹配结果。典型场景包括配合天气查询API使用，或帮助用户快速定位目标城市的唯一标识符。当前版本无需鉴权，直接调用即可。 ## 请求说明 - **URL**：`https://api.xunjinlu.fun/api/weather/csid.php` - **方法**：GET - **请求头**：`Accept: application/json`（推荐） ## 请求参数 | 名称 | 类型 | 必填 | 说明 | |--------|--------|------|--------------------------| | `city` | string | 是 | 需查询的城市名称，支持模糊匹配 | ## 返回字段表 | 字段名 | 类型 | 说明 | |--------------|---------|----------------------------------------------------------------------| | `code` | int | HTTP状态码或业务码（200表示成功） | | `message` | string | 响应状态描述（如"success"） | | `data` | object | 响应数据主体 | | `data.success` | boolean | 查询是否成功 | | `data.type` | string | 匹配类型（如"substring"表示模糊匹配） | | `data.count` | int | 匹配结果数量 | | `data.results` | array | 匹配结果列表 | | `data.results[].name` | string | 城市名称 | | `data.results[].id` | string | 城市ID | | `data.results[].type` | string | 匹配类型（同上） | | `data.results[].position` | int | 匹配位置（原始字符串中的起始索引） | | `time` | string | 服务器响应时间（格式：YYYY-MM-DD HH:MM:SS） | ## 返回 JSON 示例 ### 成功 ```json { "code": 200, "message": "success", "data": { "success": true, "type": "substring", "count": 3, "results": [ { "name": "北京市朝阳", "id": "101010300", "type": "substring", "position": 9 }, ... ] }, "time": "2025-02-26 10:30:00" } ``` ### 失败（示例） ```json { "code": 400, "message": "City parameter is required", "data": null, "time": "2025-02-26 10:30:00" } ``` ## 错误与状态 - `200`：成功 - `400`：请求参数错误（如缺少必填参数） - `404`：接口路径不存在 - 其他状态码以实际返回的 `message` 为准 ## 调用示例 ### 直接访问 ``` https://api.xunjinlu.fun/api/weather/csid.php?city=朝阳 ``` ### cURL ```bash curl -X GET "https://api.xunjinlu.fun/api/weather/csid.php?city=朝阳" -H "Accept: application/json" ``` ### Python requests ```python import requests url = "https://api.xunjinlu.fun/api/weather/csid.php" params = {"city": "朝阳"} response = requests.get(url, params=params) print(response.json()) ``` ### PHP ```php "朝阳"]; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $url . "?" . http_build_query($params)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); curl_close($ch); echo $response; ?> ``` ### HTML ```html ```