SOJSON天气API接口文档

接口概述

基于SOJSON天气API封装的PHP代理接口，支持城市名称查询和城市ID查询两种方式。自动将城市名称转换为对应的城市代码，无需手动查找城市ID。

接口地址：https://api.xunjinlu.fun/api/weather/v2.php
请求方式：GET / POST
返回格式：JSON

城市ID文件下载 https://api.xunjinlu.fun/api/weather/csid.json

核心特性

特性	说明
智能名称匹配	支持中文城市名自动匹配（如"北京"、"北京市"均可识别）
双模式查询	支持 `city` 名称参数或 `cityId` 数字ID参数
数据标准化	统一返回格式，包含实时天气、空气质量、未来预报
容错处理	自动清理"市/县/区/省"等后缀，提高匹配成功率

请求参数

[
  {
    "name": "city",
    "type": "string",
    "required": false,
    "description": "城市名称，如：北京、上海、广州。优先使用此参数，系统自动转换为城市ID"
  },
  {
    "name": "cityId",
    "type": "string",
    "required": false,
    "description": "9位数字城市代码，如：101010100（北京）。当city参数为空时使用"
  }
]

注意：city 和 cityId 至少传入一个，同时传入时优先使用 city。

响应示例

成功响应（200）

{
  "code": 200,
  "message": "success",
  "data": {
    "update_time": "2026-03-13 17:30:00",
    "city_info": {
      "city": "北京",
      "city_id": "101010100",
      "parent": "北京",
      "weather_update_time": "17:25"
    },
    "current": {
      "date": "13",
      "temperature": "18",
      "humidity": "45%",
      "pm25": 35,
      "pm10": 68,
      "quality": "良",
      "cold_index": "各项气象条件适宜，发生感冒机率较低。"
    },
    "yesterday": {
      "date": "12",
      "high": "高温 20℃",
      "low": "低温 8℃",
      "type": "晴",
      "fx": "北风",
      "fl": "3级",
      "aqi": 45
    },
    "forecast": [
      {
        "date": "14",
        "high": "高温 22℃",
        "low": "低温 10℃",
        "type": "多云",
        "fx": "南风",
        "fl": "2级",
        "aqi": 52
      }
    ]
  },
  "time": "2026-03-13 17:30:25"
}

参数错误（400）

{
  "code": 400,
  "message": "缺少必要参数: city 或 cityId",
  "data": {
    "example": {
      "name_query": "?city=北京",
      "id_query": "?cityId=101010100"
    }
  },
  "time": "2026-03-13 17:30:25"
}

城市未找到（400）

{
  "code": 400,
  "message": "未找到匹配的城市: 不存在的城市名",
  "data": {
    "input": "不存在的城市名",
    "tip": "请检查城市名称是否正确，或直接使用cityId参数"
  },
  "time": "2026-03-13 17:30:25"
}

服务器错误（500）

{
  "code": 500,
  "message": "天气查询失败: HTTP状态码: 404",
  "data": null,
  "time": "2026-03-13 17:30:25"
}

使用示例

示例1：通过城市名称查询（推荐）

curl "https://api.xunjinlu.fun/api/weather/v2.php?city=北京"

示例2：通过城市ID查询

curl "https://api.xunjinlu.fun/api/weather/v2.php?cityId=101010100"

示例3：POST请求

curl -X POST "https://api.xunjinlu.fun/api/weather/v2.php" \
  -d "city=上海"

数据字段说明

字段路径	类型	说明
`data.update_time`	string	数据更新时间
`data.city_info.city`	string	城市名称
`data.city_info.city_id`	string	城市代码
`data.current.temperature`	string	当前温度（℃）
`data.current.humidity`	string	湿度百分比
`data.current.pm25`	int	PM2.5指数
`data.current.quality`	string	空气质量等级
`data.current.cold_index`	string	感冒指数建议
`data.yesterday`	object	昨日天气回顾
`data.forecast`	array	未来5天预报

启用	参数名	参数值	数据类型	参数说明	操作

SOJSON天气API接口文档

接口概述

城市ID文件下载 https://api.xunjinlu.fun/api/weather/csid.json

核心特性

请求参数

Body 类型说明

尋鯨錄

快捷入口

热门资讯