JerryWeatherAPI v1.2

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

接口概览

认证与限制

天气查询

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

查询参数

请求示例

# 自动检测 IP（精度为省级，可能显示省会）
curl http://localhost:3000/api/weather

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

# 按经纬度查询（GPS 精确定位，API 自动反向地理编码返回城市名）
curl http://localhost:3000/api/weather?lat=37.07&lon=114.50

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

// 浏览器 GPS → API 精确定位
navigator.geolocation.getCurrentPosition(async (pos) => {
  const resp = await fetch(
    `/api/weather?lat=${pos.coords.latitude}&lon=${pos.coords.longitude}`
  );
  const data = await resp.json();
  console.log(data.location.city); // "邢台市"
});

交互测试

IP 定位调试

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

健康检查

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

参数说明

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

响应格式

成功响应 (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)：

在线演示

直接调用 API 获取当前天气数据并展示。IP 定位精度为省级，GPS 定位可精确到城市：

代码示例

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); // "晴天"

嵌入到网站/博客

方式一：嵌入脚本（推荐）

在博客/网站中添加两行代码即可。脚本会自动请求浏览器定位权限，获取精确 GPS 坐标后调用 API。

<!-- 放在你想要显示天气的位置 -->
<div id="jerry-weather"></div>
<script src="https://your-domain.vercel.app/embed.js"></script>

自定义配置

<div id="my-weather"></div>
<script>
  window.JerryWeatherConfig = {
    container: '#my-weather',   // 容器选择器
    apiBase: 'https://your-domain.vercel.app'  // API 地址
  };
</script>
<script src="https://your-domain.vercel.app/embed.js"></script>

定位策略

JavaScript API

// 手动刷新天气
JerryWeather.refresh();

// 重新获取 GPS 定位（清除缓存后重试）
JerryWeather.relocate();

// 按城市搜索
JerryWeather.search('邢台');

// 清除缓存的 GPS 坐标
JerryWeather.clearCache();

方式二：手动调用（带 GPS）

如果你有自己的前端代码，可以直接获取 GPS 坐标后调用 API。API 会自动反向地理编码，返回真实城市名：

if (navigator.geolocation) {
  navigator.geolocation.getCurrentPosition(async (pos) => {
    const resp = await fetch(
      `/api/weather?lat=${pos.coords.latitude}&lon=${pos.coords.longitude}`
    );
    const data = await resp.json();
    console.log(data.location.city);       // "邢台市"（自动反向地理编码）
    console.log(data.location.provider);   // "gps"
    console.log(data.current.temperature);
  }, (err) => {
    // GPS 被拒绝 → 降级到 IP 定位
    fetch('/api/weather').then(r => r.json()).then(console.log);
  });
}

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