<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 腾讯天气

> 腾讯天气官方数据源，中文省市名直接查询全国天气，无需经纬度。

输入省 + 市（可选区县）即可获取：实时天气、空气质量（AQI/PM2.5/PM10）、未来 7 天预报、24 小时逐时预报、23 项生活指数、日出日落与机动车限行信息。数据来自腾讯天气，权威稳定。完全免费：未登录每日 500 次，登录用户每日 1000 次。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `tencent-weather` |
| 接口名称 | 腾讯天气 |
| 接口地址 | `https://v1.apizero.cn/api/tencent-weather` |
| 请求方法 | `POST` |
| 分类 | life |
| 提供方 | 腾讯天气 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 10 req/s |
| 每日免费额度 | 1000 次（已认证用户） |
| 匿名每日额度 | 500 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

完全免费。未登录每日 500 次；携带 API Key（Authorization: Bearer <key>）登录用户每日 1000 次。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `province` | `string` | 是 | 省 / 直辖市（中文名） | `广东` |
| `city` | `string` | 是 | 市（中文名） | `深圳` |
| `county` | `string` | 否 | 区 / 县（中文名），可提升定位精度与限行准确度 | `南山` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer <你的 API Key>（可选，登录用户额度更高） | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/tencent-weather" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "province": "广东",
  "city": "深圳",
  "county": "南山"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/tencent-weather",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "province": "广东",
    "city": "深圳",
    "county": "南山",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/tencent-weather", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "province": "广东",
    "city": "深圳",
    "county": "南山"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"province":"广东","city":"深圳","county":"南山"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/tencent-weather", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "province" => "广东",
    "city" => "深圳",
    "county" => "南山",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/tencent-weather");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `location` | `object` | 查询位置 { province, city, county? } | — |
| `observe` | `object` | 实时天气（weather/temperature/humidity/wind_direction/wind_power/update_time 等） | — |
| `air` | `object` | 空气质量（aqi/level/quality/pm25/pm10/so2/no2/o3/co） | — |
| `daily_forecast` | `array` | 未来 7 天预报（含昼夜天气、风向风力、最高/最低温） | — |
| `hourly_forecast` | `array` | 未来 24 小时逐时预报 | — |
| `life_index` | `array` | 生活指数（穿衣/舒适/感冒/运动/紫外线等 23 项） | — |
| `sunrise_sunset` | `array` | 未来数日日出日落时间 | — |
| `alarm` | `array` | 气象预警列表（无预警时为空数组） | — |
| `limit` | `object` | 机动车尾号限行（无则为 null） | — |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "location": {"province": "广东", "city": "深圳", "county": "南山"},
    "observe": {"weather": "多云", "temperature": 30, "humidity": 77, "wind_direction": "北风", "wind_power": "3-4", "update_time": "2026-07-01 10:15"},
    "air": {"aqi": 13, "level": 1, "quality": "优", "pm25": 4, "pm10": 12},
    "daily_forecast": [{"date": "2026-07-01", "temperature": {"min": 26, "max": 33}}],
    "hourly_forecast": [{"time": "07-01 10:00", "temperature": 30, "weather": "多云"}],
    "life_index": [{"key": "clothes", "name": "穿衣", "level": "炎热", "detail": "..."}],
    "sunrise_sunset": [{"date": "2026-07-01", "sunrise": "05:43", "sunset": "19:12"}],
    "alarm": [],
    "limit": {"tail_number": "3和8", "date": "2026-07-01"}
  },
  "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 缺少 province/city，或地名无效（未查到对应城市） |
| `4029` | `RATE_LIMITED` | 调用过快，请稍后再试 |
| `4030` | `QUOTA_EXCEEDED` | 今日额度已用完 |
| `5020` | `UPSTREAM_ERROR` | 天气服务暂不可用 |
| `5021` | `UPSTREAM_INVALID` | 天气数据格式异常 |

## 9. 变更日志

- **v1.0** (2026-07-01)
  - 首次上线，支持实时/7天/24小时/空气质量/生活指数/日出日落/预警/限行。

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/tencent-weather`

Source: `https://apizero.cn/aidocs/tencent-weather/raw.md`
Last updated: 2026-07-01T10:39:07+08:00