JerryWeatherAPI v1.1

自动获取访问者 IP 地理位置并返回对应天气信息的 RESTful API。支持按城市名、IP 地址、经纬度查询天气，数据全面，无需 API Key。

接口概览

Base URL	`http://localhost:3000`
协议	HTTPS (Vercel) / HTTP (本地)
认证	无需认证免费
限流	每日 10,000 次 (Open-Meteo 限制)
缓存	5 分钟内存缓存
CORS	允许所有来源 (`*`)

认证与限制

天气查询

GET /api/weather

获取天气数据。支持四种查询模式（按优先级排序）：

查询参数

参数	类型	必填	说明
`city`	string	否	城市名称（中文或英文），如 `邢台`、`Beijing`、`New York`。使用时优先级最高
`lat`	number	否	纬度，需与 `lon` 同时使用。如 `37.07`
`lon`	number	否	经度，需与 `lat` 同时使用。如 `114.50`
`ip`	string	否	指定 IP 地址查询。如 `8.8.8.8`。不传则自动检测访问者 IP

请求示例

# 自动检测 IP
curl http://localhost:3000/api/weather

# 按城市查询
curl http://localhost:3000/api/weather?city=邢台

# 按经纬度查询
curl http://localhost:3000/api/weather?lat=37.07&lon=114.50

# 按指定 IP 查询
curl http://localhost:3000/api/weather?ip=8.8.8.8

交互测试

GET /api/weather

IP 定位调试

GET /api/location

调试用端点。返回检测到的 IP 地址、定位来源（provider）和地理信息，用于排查定位不准确的问题。

参数	类型	必填	说明
`ip`	string	否	指定 IP 地址。不传则自动检测

GET /api/location

健康检查

GET /api/health

检查 API 服务状态。无需参数。

GET /api/health

参数说明

各查询模式按以下优先级处理，仅第一个匹配的模式会被执行：

优先级	模式	所需参数	定位来源
1	城市搜索	`city`	Open-Meteo Geocoding API
2	坐标查询	`lat` + `lon`	直接使用坐标
3	IP 查询	`ip`	ip-api.com → ipwho.is
4	自动检测	（无参数）	从请求头提取 IP

响应格式

成功响应 (200)

{
  "success": true,
  "cached": false,
  "location": {
    "ip": "xxx.xxx.xxx.xxx",
    "city": "邢台",
    "region": "Hebei",
    "country": "China",
    "latitude": 37.0682,
    "longitude": 114.5048,
    "timezone": "Asia/Shanghai"
  },
  "current": {
    "temperature": 28.5,
    "apparentTemperature": 31.2,
    "weatherCode": 0,
    "weatherDescription": "Clear sky",
    "weatherDescriptionZh": "晴天",
    "humidity": 52,
    "windSpeed": 8.5,
    "windDirection": 180,
    "windDirectionText": "S",
    "pressure": 1010.2,
    "cloudCover": 0,
    "precipitation": 0,
    "uvIndex": 5.8,
    "visibility": 16000,
    "isDay": true
  },
  "hourly": [ /* 未来 48 小时 */ ],
  "daily": [ /* 未来 7 天 */ ],
  "fetchedAt": "2026-08-10T10:00:00.000Z",
  "units": {
    "temperature": "°C",
    "windSpeed": "km/h",
    "precipitation": "mm",
    "pressure": "hPa",
    "visibility": "meters"
  }
}

错误响应 (500)

{
  "success": false,
  "error": "INTERNAL_ERROR",
  "message": "Unable to determine geolocation...",
  "timestamp": "2026-08-10T10:00:00.000Z"
}

天气代码参考

WMO Weather interpretation codes (来自 Open-Meteo)：

Code	英文	中文	图标

在线演示

直接调用 API 获取当前天气数据并展示：

代码示例

JavaScript (fetch)

// 按城市查询
const resp = await fetch('/api/weather?city=邢台');
const data = await resp.json();
console.log(data.location.city);        // "邢台"
console.log(data.current.temperature);   // 28.5
console.log(data.current.weatherDescriptionZh); // "晴天"

// 自动定位
const resp2 = await fetch('/api/weather');
const data2 = await resp2.json();

Python (requests)

import requests

# 按城市查询
resp = requests.get('https://your-domain.vercel.app/api/weather',
                    params={'city': '邢台'})
data = resp.json()
print(data['location']['city'])      # 邢台
print(data['current']['temperature'])  # 28.5

Node.js (axios)

const axios = require('axios');

const { data } = await axios.get('/api/weather', {
  params: { city: '邢台' }
});
console.log(data.current.weatherDescriptionZh); // "晴天"

JerryWeatherAPI v1.1 · Powered by Open-Meteo & ip-api.com · 无需 API Key · 可部署在 Vercel