天气查询API V3(正在优化街道级天气)

# 天气查询API接口文档 (v3) ## 接口概述 天气查询API是一个实时天气数据接口，支持**当天天气**、**7天预报**、**40天长期预报**三种查询模式。通过本地缓存机制（30分钟有效期）大幅提升响应速度。 支持两种查询方式： - **城市天气ID查询**：直接传入9位城市代码（如 `101010200`），精准定位城市 - **城市名称查询**：传入城市名称（如 `海淀`、`北京`），自动从本地城市数据库匹配对应的天气ID ## 接口地址 ``` GET/POST https://api.xunjinlu.fun/api/weather/v3.php ``` ## 请求方式 - `GET` - 通过URL参数传递 - `POST` - 通过表单格式传递 ## 请求参数 ### 参数说明 | 参数名 | 类型 | 必填 | 默认值 | 说明 | |--------|------|------|--------|------| | cityid | string | 条件必填 | - | 城市天气代码（9位数字，如 `101010200`）。与 `cityname` 二选一，两者都不传则返回错误 | | cityname | string | 条件必填 | - | 城市名称（如 `海淀`、`北京`、`朝阳区`）。支持中文名、简称、拼音，自动匹配城市ID。与 `cityid` 二选一 | | type | string | 否 | `1d` | 天气查询类型：`1d`=当天天气（默认），`7d`=7天预报，`40d`=40天长期预报 | ### JSON 请求参数示例 ```json [ { "name": "cityid", "type": "string", "required": false, "description": "城市天气代码（9位数字）。可通过城市天气ID查询接口获取。与 cityname 二选一。", "example": "101010200" }, { "name": "cityname", "type": "string", "required": false, "description": "城市名称、简称或拼音。支持中文、拼音，自动从本地城市数据库匹配对应天气ID。与 cityid 二选一。", "example": "海淀" }, { "name": "type", "type": "string", "required": false, "description": "天气查询类型。1d=当天天气（默认），7d=7天预报，40d=40天长期预报。", "example": "1d" } ] ``` #### 请求示例 **按城市ID查询当天天气（type可省略，默认为1d）：** ``` GET ?cityid=101010200 GET ?cityid=101010200&type=1d ``` **按城市ID查询7天预报：** ``` GET ?cityid=101010200&type=7d ``` **按城市ID查询40天长期预报：** ``` GET ?cityid=101010200&type=40d ``` **按城市名称查询：** ``` GET ?cityname=海淀&type=1d GET ?cityname=北京&type=7d GET ?cityname=深圳&type=40d ``` **按拼音查询：** ``` GET ?cityname=Beijing&type=7d GET ?cityname=Chaoyang&type=1d ``` ## 查询策略说明 ### 城市名称匹配策略 当使用 `cityname` 参数时，接口采用三级匹配策略： | 优先级 | 匹配类型 | 说明 | |--------|----------|------| | 1 | 精确匹配 | 输入与 `name`、`short_name` 或 `pin_yin`（忽略大小写）完全一致 | | 2 | 模糊匹配 | 输入包含在 `name` 或 `short_name` 中，返回所有匹配结果 | | 3 | 智能选择 | 如果匹配到多个城市，优先选择区县级（`city_lv=3`）精确匹配；否则返回匹配列表让用户选择 | ### 缓存策略 | 项目 | 说明 | |------|------| | 缓存有效期 | **30分钟**（1800秒） | | 缓存命中 | 直接返回本地数据，响应时间 < 10ms | --- ## 响应参数 ### 成功响应 - 当天天气 (type=1d) 用户输入 `?cityid=101010200&type=1d`，返回当天详细天气： ```json { "code": 200, "message": "success", "data": { "city_id": "101010200", "type": "1d", "location": { "city_code": "101010200", "city_name": "海淀", "full_name": "中国,北京,北京市,海淀区", "province": "北京", "city": "北京市", "district": "海淀区", "city_lv": 3, "lng": 116.29812, "lat": 39.95931 }, "from_cache": false, "fetch_ms": 343.59, "weather": { "city": "海淀", "city_name": "中国,北京,北京市,海淀区", "update_time": "18:00", "summary": "05月23日20时 周六 多云 17/28°C", "night": { "title": "23日夜间", "icon": "n01", "weather": "多云", "temp": "17", "wind_direction": "南风", "wind_speed": "<3级", "sunset": "日落 19:29" }, "day": { "title": "24日白天", "icon": "d01", "weather": "多云", "temp": "28", "wind_direction": "南风", "wind_speed": "<3级", "sunrise": "日出 04:53" }, "hourly": [ { "time": "23日23时", "icon": "n01", "weather": "多云", "temp": "20℃", "wind_direction": "西南风", "wind_speed": "<3级", "rain_prob": "0" } ], "observe": [ { "hour": "23", "temp": "22.4", "wind_angle": "202", "wind_direction": "西南风", "wind_speed_level": "1", "rain": "0", "humidity": "86", "air_pressure": "" } ], "life_index": [ { "level": "少发", "name": "感冒指数", "desc": "无明显降温，感冒机率较低。" }, { "level": "适宜", "name": "运动指数", "desc": "天气较好，尽情感受运动的快乐吧。" }, { "level": "较舒适", "name": "穿衣指数", "desc": "建议穿薄外套或牛仔裤等服装。" }, { "level": "适宜", "name": "洗车指数", "desc": "天气较好，适合擦洗汽车。" }, { "level": "很强", "name": "紫外线指数", "desc": "涂擦SPF20以上，PA++护肤品，避强光。" }, { "level": "较易发", "name": "过敏指数", "desc": "外出需远离过敏源，适当采取防护措施。" } ] } }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 成功响应 - 7天预报 (type=7d) 用户输入 `?cityid=101010200&type=7d`，返回7天天气预报： ```json { "code": 200, "message": "success (cached)", "data": { "city_id": "101010200", "type": "7d", "location": { "city_code": "101010200", "city_name": "海淀", "full_name": "中国,北京,北京市,海淀区", "province": "北京", "city": "北京市", "district": "海淀区", "city_lv": 3, "lng": 116.29812, "lat": 39.95931 }, "from_cache": true, "fetch_ms": 4.33, "weather": { "city": "海淀", "city_name": "中国,北京,北京市,海淀区", "update_time": "18:00", "summary": "05月23日20时 周六 多云 17/28°C", "days": [ { "date": "23日（今天）", "icon_night": "n01", "weather": "多云", "temp_low": "17℃", "wind_direction": "南风", "wind_speed": "<3级" }, { "date": "24日（明天）", "icon_day": "d01", "icon_night": "n01", "weather": "多云", "temp_high": "28℃", "temp_low": "18℃", "wind_direction": "南风转东北风", "wind_speed": "<3级" }, { "date": "25日（后天）", "icon_day": "d07", "icon_night": "n02", "weather": "小雨转阴", "temp_high": "21℃", "temp_low": "16℃", "wind_direction": "东北风", "wind_speed": "<3级" } ], "hourly": [ [ { "time": "24日08时", "icon": "d01", "weather": "多云", "temp": "20℃", "wind_direction": "东风", "wind_speed": "<3级", "rain_prob": "2" } ] ] } }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 成功响应 - 40天长期预报 (type=40d) 用户输入 `?cityid=101010200&type=40d`，返回40天长期天气预报： ```json { "code": 200, "message": "success", "data": { "city_id": "101010200", "type": "40d", "location": { "city_code": "101010200", "city_name": "海淀", "full_name": "中国,北京,北京市,海淀区", "province": "北京", "city": "北京市", "district": "海淀区", "city_lv": 3, "lng": 116.29812, "lat": 39.95931 }, "from_cache": false, "fetch_ms": 1250.42, "weather": { "city_name": "中国,北京,北京市,海淀区", "update_time": { "time": "18:00", "update": "yes" }, "days": [ { "date": "20260523", "nl": "廿七", "hmax": "28", "hmin": "16", "temp_high": "28", "temp_low": "17", "weather_day": "多云", "wind_day": "南风", "wind_speed_day": "<3级", "icon_day": "d01", "icon_night": "n01", "max_obs": "28.5", "min_obs": "15.2", "rain_obs": "0", "rain_prob": "10%", "desc": "", "alarm_t1": "", "alarm_t1_text": "", "aqi_t2": "", "alarm_t3": "", "alarm_t3_text": "", "fe": "", "jq": "", "yl": "", "hol": "", "wor": "", "sky_blue": "lv2" } ], "total": 40 } }, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 多城市匹配响应 用户输入 `?cityname=朝阳&type=7d`，匹配到多个同名城市： ```json { "code": 300, "message": "匹配到多个城市，请选择指定城市后使用 cityid 参数请求", "data": { "matches": [ { "city_code": "101010300", "city_name": "朝阳", "full_name": "中国,北京,北京市,朝阳区", "city_lv": 3 }, { "city_code": "101060101", "city_name": "朝阳", "full_name": "中国,吉林省,长春市,朝阳区", "city_lv": 3 } ], "hint": "请使用 cityid 参数直接指定城市，如: ?cityid=101010300&type=7d" }, "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": "请提供 cityid 或 cityname 参数", "data": null, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 错误响应（无效的 type 参数） ```json { "code": 400, "message": "无效的 type 参数，可选值: 1d(当天), 7d(7天), 40d(40天)", "data": null, "time": "2026-05-23 12:00:00", "api_info": { "developer": "尋鯨錄", "blog": "https://www.xunjinlu.fun", "api_platform": "https://api.xunjinlu.fun" } } ``` ### 错误响应（无效的 cityid 格式） ```json { "code": 400, "message": "无效的 cityid 格式，应为9位数字，如: 101010200", "data": null, "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": null, "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": "7天天气数据解析失败，页面结构可能已变更", "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=成功，300=多城市匹配需选择，400=参数错误，404=城市未找到，500=服务器/解析错误 | | message | string | 状态描述信息。成功时：走缓存返回 `"success (cached)"`，实时获取返回 `"success"` | | data | object/null | 查询结果数据，失败时为 null | | time | string | 服务器响应时间，格式 `YYYY-MM-DD HH:MM:SS` | | api_info | object | API开发者信息 | ### data 字段（成功时） | 字段 | 类型 | 说明 | |------|------|------| | data.city_id | string | 城市天气代码（9位数字） | | data.type | string | 查询类型：`1d` / `7d` / `40d` | | data.location | object | 城市地理位置信息（从城市ID数据库提取，解决官网显示"城区"等不准确问题），详见下方 location 字段说明 | | data.from_cache | bool | 是否来自缓存：`true`=本地缓存命中，`false`=实时获取 | | data.fetch_ms | float | 数据获取耗时（毫秒）。缓存命中时通常 < 10ms | | data.weather | object | 天气数据主体，结构因 type 不同而异 | ### data.location 字段说明 `location` 字段从城市ID数据库（csid.json）中提取，解析完整的地理层级信息。当官网 HTML 中城市名显示为"城区"等不准确名称时，可通过此字段获取正确的省/市/区名称。 | 字段 | 类型 | 说明 | |------|------|------| | location.city_code | string | 城市天气代码 | | location.city_name | string | 城市天气名称（简称，如 `北京`、`海淀`、`广州`） | | location.full_name | string | 完整地区层级路径（如 `中国,北京,北京市,海淀区`） | | location.province | string | 省级名称（如 `北京`、`广东省`） | | location.city | string | 市级名称（如 `北京市`、`广州市`） | | location.district | string | 区县级名称（如 `海淀区`），非区县级时为空字符串 | | location.city_lv | int | 地区层级：`1`=省、`2`=市、`3`=区县 | | location.lng | float | 经度坐标 | | location.lat | float | 纬度坐标 | > **说明**: 匹配优先级为 市级(city_lv=2) > 区县级(city_lv=3) > 省级(city_lv=1)。因为同一个 city_code 可能被多个下级地区共用（如 `101010100` 同时被北京、东城区、西城区共用），优先选取市级条目最能代表该天气代码对应的城市主体。 ### data.weather 字段 - 当天天气 (type=1d) | 字段 | 类型 | 说明 | |------|------|------| | weather.city | string | 城市名称（官网HTML原始值，部分城市可能显示为"城区"） | | weather.city_name | string | 完整地区路径（从城市ID数据库提取，格式如 `中国,北京,北京市,海淀区`） | | weather.update_time | string | 数据更新时间（如 `18:00`） | | weather.summary | string | 天气概要描述（如 `05月23日20时 周六 多云 17/28°C`） | | weather.night | object | 夜间天气数据 | | weather.day | object | 白天天气数据 | | weather.hourly | array | 每3小时精细预报数据（8条） | | weather.observe | array | 过去24小时实况观测数据（24条，每小时一条） | | weather.life_index | array | 生活指数（感冒/运动/穿衣/洗车/紫外线/过敏等） | #### weather.night / weather.day 子字段 | 字段 | 类型 | 说明 | |------|------|------| | title | string | 时段标题（如 `23日夜间`、`24日白天`） | | icon | string | 天气图标代码（如 `n01`=夜间多云，`d01`=白天多云） | | weather | string | 天气现象（如 `多云`、`小雨`） | | temp | string | 温度数值 | | wind_direction | string | 风向（如 `南风`、`北风`） | | wind_speed | string | 风力等级（如 `<3级`、`3-4级`） | | sunrise | string | 日出时间（仅白天有，如 `日出 04:53`） | | sunset | string | 日落时间（仅夜间有，如 `日落 19:29`） | #### weather.hourly[] 子字段 | 字段 | 类型 | 说明 | |------|------|------| | time | string | 预报时间（如 `23日23时`） | | icon | string | 天气图标代码 | | weather | string | 天气现象 | | temp | string | 温度 | | wind_direction | string | 风向 | | wind_speed | string | 风力等级 | | rain_prob | string | 降水概率（`0`~`3`，越大越可能降水） | #### weather.observe[] 子字段 | 字段 | 类型 | 说明 | |------|------|------| | hour | string | 观测时间（小时，如 `23`、`00`） | | temp | string | 实测温度（℃） | | wind_angle | string | 风向角度 | | wind_direction | string | 风向描述 | | wind_speed_level | string | 风力等级 | | rain | string | 降水量 | | humidity | string | 湿度（%） | | air_pressure | string | 气压 | #### weather.life_index[] 子字段 | 字段 | 类型 | 说明 | |------|------|------| | level | string | 指数等级（如 `少发`、`适宜`、`很强`） | | name | string | 指数名称（如 `感冒指数`、`穿衣指数`） | | desc | string | 指数详细描述 | ### data.weather 字段 - 7天预报 (type=7d) | 字段 | 类型 | 说明 | |------|------|------| | weather.city | string | 城市名称 | | weather.update_time | string | 数据更新时间 | | weather.summary | string | 天气概要描述 | | weather.days | array | 7天每日天气数据（7条） | | weather.hourly | array | 7天内每3小时精细预报数据（按天分组） | #### weather.days[] 子字段 | 字段 | 类型 | 说明 | |------|------|------| | date | string | 日期描述（如 `23日（今天）`、`24日（明天）`） | | icon_day | string | 白天天气图标代码（如 `d01`） | | icon_night | string | 夜间天气图标代码（如 `n01`） | | weather | string | 天气现象（如 `多云`、`小雨转阴`） | | temp_high | string | 最高温度（如 `28℃`，今天可能无此字段） | | temp_low | string | 最低温度（如 `17℃`） | | wind_direction | string | 风向（如 `南风转东北风`） | | wind_speed | string | 风力等级（如 `<3级`、`3-4级转<3级`） | ### data.weather 字段 - 40天预报 (type=40d) | 字段 | 类型 | 说明 | |------|------|------| | weather.update_time | object | 数据更新时间信息 | | weather.days | array | 40天每日天气数据（40条） | | weather.total | int | 总天数（40） | #### weather.days[] 子字段 | 字段 | 类型 | 说明 | |------|------|------| | date | string | 日期（`YYYYMMDD` 格式，如 `20260523`） | | nl | string | 农历日期（如 `廿七`） | | hmax | string | 历史均值最高温度 | | hmin | string | 历史均值最低温度 | | temp_high | string | 预报最高温度 | | temp_low | string | 预报最低温度 | | weather_day | string | 白天天气现象 | | wind_day | string | 白天风向 | | wind_speed_day | string | 白天风力等级 | | icon_day | string | 白天天气图标代码（如 `d01`） | | icon_night | string | 夜间天气图标代码（如 `n01`） | | max_obs | string | 实况最高温度（历史日期有值） | | min_obs | string | 实况最低温度（历史日期有值） | | rain_obs | string | 实况降水量（mm，历史日期有值） | | rain_prob | string | 降水概率（如 `33%`） | | desc | string | 天气描述 | | alarm_t1 | string | 预警类型1（如 `降温`） | | alarm_t1_text | string | 预警描述1 | | aqi_t2 | string | 空气质量提示 | | alarm_t3 | string | 预警类型3 | | alarm_t3_text | string | 预警描述3 | | fe | string | 特殊天气标记 | | jq | string | 节气名称（如 `夏至`、`小暑`） | | yl | string | 月历节日 | | hol | string | 节假日标记（`200`=休息日） | | wor | string | 调休工作日标记（`200`=上班日） | | sky_blue | string | 蓝天等级（`lv1`~`lv5`，数值越小越蓝） | ### api_info 字段 | 字段 | 类型 | 说明 | |------|------|------| | api_info.developer | string | 开发者名称 | | api_info.blog | string | 开发者博客地址 | | api_info.api_platform | string | API平台地址 | ### 天气图标代码对照表 | 代码 | 含义 | 代码 | 含义 | 代码 | 含义 | |------|------|------|------|------|------| | d00/n00 | 晴 | d01/n01 | 多云 | d02/n02 | 阴 | | d03/n03 | 阵雨 | d04/n04 | 雷阵雨 | d05/n05 | 雷阵雨伴冰雹 | | d06/n06 | 雨夹雪 | d07/n07 | 小雨 | d08/n08 | 中雨 | | d09/n09 | 大雨 | d10/n10 | 暴雨 | d11/n11 | 大暴雨 | | d12/n12 | 特大暴雨 | d13/n13 | 阵雪 | d14/n14 | 小雪 | | d15/n15 | 中雪 | d16/n16 | 大雪 | d17/n17 | 暴雪 | | d18/n18 | 雾 | d19/n19 | 冻雨 | d20/n20 | 沙尘暴 | | d21/n21 | 小到中雨 | d22/n22 | 中到大雨 | d23/n23 | 大到暴雨 | | d24/n24 | 暴雨到大暴雨 | d25/n25 | 大暴雨到特大暴雨 | d26/n26 | 小到中雪 | | d27/n27 | 中到大雪 | d28/n28 | 大到暴雪 | d29/n29 | 浮尘 | | d30/n30 | 扬沙 | d31/n31 | 强沙尘暴 | d53/n53 | 霾 | --- ## 状态码说明 | 状态码 | 含义 | 说明 | |--------|------|------| | 200 | 成功 | 查询成功，天气数据正常返回 | | 300 | 多城市匹配 | 城市名称匹配到多个结果，需用户选择指定城市后使用 cityid 参数请求 | | 400 | 参数错误 | 缺少必要参数、type 值无效或 cityid 格式错误 | | 404 | 未找到 | 城市名称在数据库中未找到匹配 | | 500 | 服务器错误 | 天气网请求失败、HTML解析失败或数据格式异常 | --- ## 数据统计 | 指标 | 数值 | |------|------| | 支持城市数量 | 3749 个（全国省/市/区县三级） | | 数据来源 | 气象数据官方平台 | | 当天天气字段 | 城市+夜间+白天+逐小时(8条)+实况(24条)+生活指数(6项) | | 7天预报字段 | 城市+7天每日+逐小时分组预报 | | 40天预报字段 | 40天每日（含农历/温度/降水/风力/节气/节假日等23个字段） | | 缓存有效期 | 30分钟 | | 响应格式 | JSON（UTF-8编码） | --- ## 注意事项 1. **跨域支持**：接口已配置CORS，支持 `*` 跨域访问 2. **数据来源**：所有天气数据实时获取，保证数据准确性和时效性 3. **缓存机制**：30分钟内重复请求同一城市同类天气数据会从本地缓存读取，大幅提升响应速度 4. **编码格式**：接口返回 UTF-8 编码的 JSON 数据，中文不会转义为 Unicode 5. **请求方式**：同时支持 GET 和 POST 请求 6. **限速建议**：请勿短时间大量请求，建议利用缓存机制合理控制请求频率 7. **40天注意**：40天预报数据来源较广，首次请求耗时较长（约1-2秒），缓存命中后极快 8. **城市代码**：可通过 [城市天气ID查询接口](./csid.md) 获取9位城市天气代码 ## 典型查询场景对照表 | 用户输入 | 说明 | 返回数据 | |----------|------|----------| | `?cityid=101010200` | 查询海淀当天天气（默认type=1d） | 当天详细天气+生活指数 | | `?cityid=101010200&type=1d` | 查询海淀当天天气 | 当天详细天气+生活指数 | | `?cityid=101010200&type=40d` | 查询海淀40天预报 | 40天长期预报数据 | | `?cityname=海淀&type=1d` | 按城市名查当天天气 | 自动匹配101010200后返回 | | `?cityname=北京` | 按城市名查7天天气 | 自动匹配101010100后返回 | | `?cityname=朝阳&type=7d` | 模糊匹配多个城市 | 返回匹配列表（北京朝阳/长春朝阳） | | `?cityname=Chaoyang&type=1d` | 按拼音查询 | 同中文名查询逻辑 | --- ## 更新日志 | 版本 | 日期 | 说明 | |------|------|------| | v3.0.0 | 2026-05-23 | 全新版本：支持当天/7天/40天三种天气查询，30分钟本地缓存，城市名自动匹配 | --- ## 开发者信息 - **开发者**：尋鯨錄 - **博客**：[https://www.xunjinlu.fun](https://www.xunjinlu.fun) - **API平台**：[https://api.xunjinlu.fun](https://api.xunjinlu.fun)

> 声明：本文档由 AI 根据平台配置自动生成；示例为片段。 ## 接口简介 天气查询API V3是一个实时天气数据接口，支持当天天气、7天预报和40天长期预报三种查询模式。数据来源于中国天气网官方页面及API，通过本地缓存机制（30分钟有效期）大幅提升响应速度并降低对源站的请求压力。接口支持通过城市ID或城市名称进行查询，并自动匹配城市信息。 ## 请求说明 - **方法**：GET - **请求头**：Content-Type: application/json - **调用地址**：https://api.xunjinlu.fun/api/weather/v3.php ## 请求参数 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | cityid | string | 是（与cityname二选一） | 城市天气代码（9位数字，如101010200） | | cityname | string | 是（与cityid二选一） | 城市名称（如海淀、北京、朝阳区） | | type | string | 否 | 查询类型：1d=当天天气（默认），7d=7天预报，40d=40天长期预报 | ## 返回字段 | 字段名 | 类型 | 说明 | |-------|------|------| | code | number | 状态码，200表示成功 | | message | string | 返回消息 | | data | object | 天气数据对象 | | data.city_id | string | 城市ID | | data.type | string | 查询类型 | | data.location | object | 位置信息 | | data.from_cache | boolean | 是否从缓存获取 | | data.fetch_ms | number | 数据获取耗时(毫秒) | | data.weather | object | 天气信息 | ## 返回示例 ### 成功示例 ```json { "code": 200, "message": "success", "data": { "city_id": "101010200", "type": "1d", "location": { "city_code": "101010200", "city_name": "海淀", "full_name": "中国,北京,北京市,海淀区", "province": "北京", "city": "北京市", "district": "海淀区", "city_lv": 3, "lng": 116.29812, "lat": 39.95931 }, "from_cache": false, "fetch_ms": 343.59, "weather": { "city": "海淀", "city_name": "中国,北京,北京市,海淀区", "update_time": "18:00", "summary": "05月23日20时 周六 多云 17/28°C", "night": { "title": "23日夜间", "icon": "n01", "weather": "多云", "temp": "17", "wind_direction": "南风", "wind_speed": "<3级", "sunset": "日落 19:29" }, "day": { "title": "24日白天", "icon": "d01", "weather": "多云", "temp": "28", "wind_direction": "南风", "wind_speed": "<3级", "sunrise": "日出 04:53" } } } } ``` ### 失败示例 ```json { "code": 400, "message": "请提供cityid或cityname参数" } ``` ## 错误码 | 错误码 | 说明 | |-------|------| | 200 | 成功 | | 400 | 请求参数错误 | | 404 | 城市未找到 | | 500 | 服务器内部错误 | | 503 | 服务暂时不可用 | ## 调用示例 ### 浏览器直接访问 https://api.xunjinlu.fun/api/weather/v3.php?cityname=北京&type=1d ### cURL ```bash curl "https://api.xunjinlu.fun/api/weather/v3.php?cityname=北京&type=1d" ``` ### Python ```python import requests url = "https://api.xunjinlu.fun/api/weather/v3.php" params = {"cityname": "北京", "type": "1d"} response = requests.get(url, params=params) print(response.json()) ``` ### PHP ```php $url = "https://api.xunjinlu.fun/api/weather/v3.php"; $params = http_build_query(["cityname" => "北京", "type" => "1d"]); $context = stream_context_create(["http" => ["header" => "Content-Type: application/json"]]); $response = file_get_contents($url . "?" . $params, false, $context); echo $response; ``` ### HTML ```html ```