develop

2026年8月26日

心知天气 Seniverse API 接入指南

本文由 Ideas/seniverse-api-guide.md（V4 注册申请流程指南）整理而来，并补充 2026 年 8 月官方最新信息：V3 接口大幅扩容（新增空气类、海洋类、农业类、气象图层、公里级网格）、V4 接口与文档地址、接口更新频率表、SDK 与示例仓库等。

最后更新: 2026-08-26 官网: https://www.seniverse.com/ V4 API 文档（语雀）: https://seniverse.yuque.com/hyper_data/api_v4/gniqvo V3 API 文档: https://docs.seniverse.com/ 官方示例仓库: https://github.com/seniverse/seniverse-api-v4-demos

一、服务简介
二、注册账号
三、获取 API 密钥（公钥 + 私钥）
四、V4 API 认证方式（HMAC-SHA1 签名）
五、V4 API 接口概览
六、V3 API 接口分类总览
七、V3 公里级网格接口示例
八、接口更新频率与滞后时间
九、免费套餐限制
十、SDK 与示例代码
十一、技术支持
十二、V3 vs V4 主要差异
十三、常见问题

一、服务简介

心知天气（Seniverse） 是北京心知科技有限公司旗下企业级高精度气象数据服务，通过标准 Restful API 接口提供天气、空气、生活指数、地理、海洋、农业、气象图层等多维度气象数据。

核心特性

公里级精度 —— 实况与预报数据空间分辨率达到公里级网格，覆盖全国每个角落
分钟级更新 —— 实时处理海量气象数据，实现分钟级天气数据更新频率
AI 增强 —— 基于机器学习和深度学习算法，进一步提升天气预报分辨率与准确性
多数据源融合 —— 融合 CMA（中国气象局）、GFS、EC（ECMWF）等数据源，数据更准确、稳定、全面

公司资质

资质	说明
中国气象局气象数据中心	合作企业
中国气象局公共气象服务中心	合作企业
国家预警信息发布中心	合作企业
北京市气象局	备案企业
中国气象服务协会	会员单位
WMO 世界气象组织旗下 HMEI	会员单位
国家级高新技术	认定企业
ISO 27001	认证

行业解决方案

心知天气针对以下行业提供深度结合的解决方案：新能源（风电、太阳能资源评估预测）、电力、交通（道路天气精细感知及预报）、农业（农业天气数据 + 植保计划 + 价格预测）、零售（需求预测、市场营销）、广告（基于环境的精准推荐）、保险（产品精算定价、风控）、移动互联网（App 天气功能模块）、智能硬件（IoT 设备天气联动）、车联网（安全驾驶、UBI 车险）。

产品矩阵

产品	说明
天气数据	标准 Restful API 接口，标准化数据访问
天气监控机器人	Hyper Bot，气象数据监控
天气数据可视化分析平台	Hyper Insights
气象灾害监控与预警系统	Hyper Alert

二、注册账号

打开心知天气官网：https://www.seniverse.com/
点击页面右上角的 「立即免费试用」 或 「注册」 按钮（也可直接访问 https://www.seniverse.com/products?iid=new）。
填写注册信息：
- 邮箱地址 — 建议使用常用邮箱（后续接收 API 通知）
- 密码 — 至少 8 位，包含字母和数字
- 手机号码 — 中国手机号（用于账户安全验证）
- 企业名称（选填）— 个人开发者可留空
点击 「创建账号」 完成注册。
系统将发送验证邮件到您的邮箱，点击邮件中的链接完成邮箱验证。

提示: 注册完成后系统会赠送 14 天免费试用，期间可全功能体验所有 API 接口，含 10,000 次免费调用额度。

三、获取 API 密钥（公钥 + 私钥）

心知天气 V4 API 采用 公钥（Public Key）+ 私钥（Private Key） 的认证方式，需要先在控制台添加 API 产品后才能获取密钥。V3 API 仍使用传统的 uid + key 方式（详见 V3 文档）。

步骤 1：添加 API 产品

登录心知天气控制台：https://www.seniverse.com/console
在左侧导航栏找到 「产品管理」。
点击 「添加产品」，选择你需要的 API 产品（如「网格天气数据」「路面气象预报」等）。
添加成功后，在产品详情页即可看到生成的密钥对。

步骤 2：获取公钥和私钥

每组密钥由 公钥（public_key） 和 私钥（private_key） 组成，例如：

公钥（Public Key）： P8itVvN3qWEhoSor
私钥（Private Key）： SgSn6OPU_0MDadrDi

步骤 3：密钥安全提醒

⚠️ 重要:

公钥可以在请求中明文传输

私钥严禁在请求中明文传输！仅用于服务器端 HMAC-SHA1 签名计算

不要将私钥硬编码在客户端代码（前端 App、网页 JavaScript）中

不要将私钥提交到公共代码仓库（GitHub 等）

建议将私钥配置在服务端环境变量或配置文件中

V4 API 没有 “私钥直接请求” 方式，必须使用签名验证

V3 API 的 key 同样不应在前端直接调用，推荐由后端代为请求或构造 JSONP 形式请求

四、V4 API 认证方式（HMAC-SHA1 签名）

V4 API 采用 HMAC-SHA1 签名验证，请求地址中只包含公钥和签名，私钥不会出现在请求中。

签名算法步骤

1. 准备参数
   - ts:        当前 UNIX 时间戳（秒，10 位）
   - ttl:       签名有效期（秒，可选，默认 1800）
   - public_key: 你的公钥
   - 其他业务参数（如 fields、locations 等）

2. 参数排序
   将所有参数按 key 的字典升序排列

3. 构建原始字符串
   key1=value1&key2=value2&key3=value3
   （注意：value 不做 URL 编码）

4. HMAC-SHA1 哈希
   以私钥作为密钥，对原始字符串进行 HMAC-SHA1 哈希

5. Base64 编码
   将哈希结果进行 Base64 编码，得到 sig

6. 构造最终 URL
   https://api.seniverse.com/v4?key1=value1&...&sig=URL_ENCODE(sig)

签名示例

Python 示例：

import hashlib
import hmac
import time
from base64 import b64encode
from urllib.parse import urlencode
from urllib.request import urlopen

public_key = "你的公钥"
private_key = "你的私钥"

# 准备参数
params = {
    "fields": "weather_hourly_1h",
    "locations": "39.93:116.40",
    "public_key": public_key,
    "ts": str(int(time.time())),
    "ttl": "600",
}

# 排序并构建原始字符串
raw_query = "&".join(f"{k}={v}" for k, v in sorted(params.items()))

# HMAC-SHA1 签名
sig = b64encode(hmac.new(
    private_key.encode(), raw_query.encode(), hashlib.sha1
).digest()).decode()

# 构造 URL
params["sig"] = sig
url = "https://api.seniverse.com/v4?" + urlencode(params)
print(url)

C# 示例（.NET）：

using System;
using System.Collections.Generic;
using System.Linq;
using System.Security.Cryptography;
using System.Text;

string publicKey = "你的公钥";
string privateKey = "你的私钥";
string ts = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
string ttl = "600";

// 1. 准备并排序参数
var parameters = new SortedDictionary<string, string>
{
    ["fields"] = "weather_hourly_1h",
    ["locations"] = "39.93:116.40",
    ["public_key"] = publicKey,
    ["ts"] = ts,
    ["ttl"] = ttl,
};

// 2. 构建原始字符串
var rawQuery = string.Join("&", parameters.Select(kvp => $"{kvp.Key}={kvp.Value}"));

// 3. HMAC-SHA1 签名
byte[] hashBytes;
using (var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(privateKey)))
{
    hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawQuery));
}
var sig = Convert.ToBase64String(hashBytes);

// 4. 构建最终 URL
var queryString = string.Join("&",
    parameters.Select(kvp => $"{kvp.Key}={Uri.EscapeDataString(kvp.Value)}"));
var url = $"https://api.seniverse.com/v4?{queryString}&sig={Uri.EscapeDataString(sig)}";
Console.WriteLine(url);

五、V4 API 接口概览

API 端点

Base URL（单一端点）：

https://api.seniverse.com/v4

可用字段（fields）

V4 API 使用 fields 参数指定查询的数据类型，支持的字段包括：

fields 值	说明	数据精度	覆盖范围
`weather_hourly_1h`	逐小时天气预报（温度、湿度、气压、风速风向、降水量等）	1 小时	全球网格
`weather_daily`	逐日天气预报	1 天	全球网格
`precip_minutely`	分钟级降水预报（未来 2 小时）	分钟级	中国
`typhoon_list`	台风列表	实时	全球
路面气象预报	中国路网 1 公里网格级，未来 2 小时分钟级预测，未来 10 天小时级预测	公里级	中国路网

💡 V4 文档地址：https://seniverse.yuque.com/hyper_data/api_v4/gniqvo

通用参数

参数	说明	必填	示例
`fields`	查询的数据类型	是	`weather_hourly_1h`
`locations`	经纬度（纬度:经度）	是	`39.93:116.40`
`public_key`	公钥	是	`P8itVvN3qWEhoSor`
`ts`	UNIX 时间戳（秒）	是	`1722249600`
`ttl`	签名有效期（秒，默认 1800）	否	`600`
`sig`	HMAC-SHA1 签名	是	`dTYeoN8WdOfW...`

调用示例

# 获取逐小时天气预报（北京）
curl "https://api.seniverse.com/v4?fields=weather_hourly_1h&locations=39.93:116.40&public_key=你的公钥&ts=1722249600&ttl=600&sig=你的签名"

# 获取分钟级降水预报
curl "https://api.seniverse.com/v4?fields=precip_minutely&locations=39.93:116.40&public_key=你的公钥&ts=1722249600&ttl=600&sig=你的签名"

响应格式

{
  "status": "OK",
  "data": {
    "weather_hourly_1h": [
      {
        "time": "2026-08-26T10:00:00+08:00",
        "temperature": 32.5,
        "humidity": 45.2,
        "pressure": 1013.2,
        "wind_speed": 12.6,
        "wind_direction": 180.0,
        "precipitation": 0.0,
        "weather_code": 0
      }
    ]
  }
}

天气代码表

V3 与 V4 共用一套天气现象代码（code / weather_code）：

代码	天气现象	代码	天气现象
0	晴	17	暴雪
1	多云	18	雾
2	阴	19	冻雨
3	阵雨	20	沙尘暴
4	雷阵雨	21	小雨-中雨
5	雷阵雨伴有冰雹	22	中雨-大雨
6	雨夹雪	23	大雨-暴雨
7	小雨	24	暴雨-大暴雨
8	中雨	25	大暴雨-特大暴雨
9	大雨	26	小雪-中雪
10	暴雨	27	中雪-大雪
11	大暴雨	28	大雪-暴雪
12	特大暴雨	29	浮尘
13	阵雪	30	扬沙
14	小雪	31	强沙尘暴
15	中雪	32	霾
16	大雪	99	无

六、V3 API 接口分类总览

V3 API 仍在 https://docs.seniverse.com/ 维护，并已大幅扩容。文档结构按数据类型分为 9 大类：

分类	状态	说明
天气类	稳定	实况、3 天 / 15 天预报、24 小时 / 15 天逐 3 小时预报、分钟级降水、历史天气
空气类	新	空气质量实况、5 天逐日预报、5 天逐小时预报、过去 24 小时历史
生活类	稳定	穿衣、运动、洗车等生活指数
地理类	稳定	城市搜索（city lookup）、拼音城市查找、IP 定位
功能类	稳定	日出日落、月相、潮汐
海洋类	新	逐小时潮汐等海洋气象数据
农业类	新	农业气象数据（土壤、农事建议等）
气象图层	新	气象要素可视化图层（雷达、卫星、降水等）
公里级网格	稳定	1×1 公里网格实况与预报（详见下节）

V3 认证方式

V3 API 提供两种鉴权方式（详见开始使用）：

直接 Key 请求 —— 在请求 URL 中携带 key=你的密钥，简单但不安全，禁止在前端使用
uid + key 签名 —— 使用 HMAC-SHA1 + Base64 签名，密钥不出现在请求中，与 V4 类似但参数为 uid 而非 public_key

V3 通用参数

V3 各接口通用参数（详见通用参数）：

参数	说明	必填	示例
`key`	你的 API 密钥（直接方式）或签名（签名方式）	是	`SgSn6OPU_0MDadrDi`
`location`	位置（城市 ID / 城市名 / 拼音 / IP / 经纬度 `纬度:经度`）	是	`beijing` / `39.93:116.40`
`language`	返回语言（`zh-Hans`、`en`、`ja`、`ko` 等）	否	`zh-Hans`
`unit`	单位（`c` 摄氏度 / `f` 华氏度）	否	`c`
`start`	起始时间（0 今天，1 明天）	否	`0`
`days`	天数（受权限控制）	否	`3`
`hours`	小时数	否	`24`

七、V3 公里级网格接口示例

公里级网格是 V3 区别于城市级 API 的核心特性，提供 1×1 公里精度的实况与预报数据，覆盖中国地区。

1. 公里级网格天气实况

端点： https://api.seniverse.com/v3/grid/now.json

参数：

参数名	类型	必填	备注
`key`	String	是	你的 API 密钥
`location`	String	是	位置（格式：纬度:经度，英文冒号分隔）
`unit`	Unit	否	单位（默认 c）

响应示例：

{
  "results": [
    {
      "location": {
        "longitude": "116.359805",
        "latitude": "39.865927"
      },
      "now_grid": {
        "temperature": "29.09",
        "humidity": "74.04",
        "wind_speed": "4.10",
        "wind_scale": "1",
        "wind_direction_degree": "106.08",
        "wind_direction": "东南",
        "precip": "0.01",
        "pressure": "998.78",
        "solar_radiation": "281.46",
        "code": "4",
        "text": "多云",
        "feels_like": "32.18",
        "vapor_pressure": "4.68"
      },
      "last_update": "2018-08-12T12:00:00+08:00"
    }
  ]
}

2. 公里级网格天气预报

端点： https://api.seniverse.com/v3/grid/hourly3h.json

获取中国地区未来 10 天逐三小时公里级天气预报。

参数：

参数名	类型	必填	备注
`key`	String	是	你的 API 密钥
`location`	String	是	位置（纬度:经度）
`unit`	Unit	否	单位（默认 c）
`start`	Int	否	起始时间（0 今天，1 明天）
`days`	Int	否	天数（受权限允许的最大天数限制）

响应示例（节选）：

{
  "results": [
    {
      "location": {
        "longitude": "116.359805",
        "latitude": "39.865927"
      },
      "data": [
        {
          "time": "2018-08-06T08:00:00+08:00",
          "temperature": "26.95",
          "humidity": "87.16",
          "precip": "2.01",
          "clouds": "84.49",
          "wind_speed": "2.95",
          "wind_scale": "1",
          "wind_direction_degree": "232.43",
          "wind_direction": "西南",
          "code": "14",
          "text": "中雨"
        }
      ],
      "last_update": "2018-08-06T11:59:25+08:00"
    }
  ]
}

八、接口更新频率与滞后时间

下表来自官方接口更新频率和滞后时间，用于评估数据新鲜度：

数据类型	更新频率	滞后时间
天气实况接口	国内城市 15 分钟左右 / 国际城市 20 分钟左右	30-60 分钟
分钟级降水预报接口	10 分钟左右	无
未来 15 天逐日预报接口	每天 3-4 次	无
24 小时逐小时预报接口	1 小时	无
过去 24 小时历史天气接口	1 小时	无
15 天逐 3 小时精细化天气预报	每天 3-4 次	无
空气质量实况接口	1 小时	30 分钟左右
未来 5 天逐日空气质量预报接口	每天一次	无
未来 5 天逐小时空气质量预报接口	1 小时	无
过去 24 小时历史空气质量	1 小时	无
生活指数接口	每天一次	无
气象灾害预警接口	1-3 分钟左右	无
逐小时潮汐接口	1 小时	无
公里级网格天气实况	1 小时	一小时
公里级网格天气预报	每天两次	无
过去 24 小时公里级天气数据	1 小时	一小时

九、免费套餐限制

调用频率限制

速率限制 —— 因产品而异（网格数据产品通常高于城市级 API）
QPS 限制 —— 因套餐而异
超出限制将返回 HTTP 429（Too Many Requests）

数据限制

V4 网格数据 API 需要 单独添加产品 并获取密钥
免费试用期间含 10,000 次调用额度
网格数据覆盖中国及全球，具体范围取决于所购产品
国内约 370 个主要城市（V3 城市级免费档）

商业使用限制

免费套餐 不得用于商业用途
免费用户须在数据展示页面注明数据来源为心知天气
付费用户可自行决定是否注明数据来源
商业使用须购买相应产品的付费套餐并签订服务协议

付费套餐参考

产品类型	起价	说明
开发者套餐	—	适合个人开发与原型
访问量套餐	¥599/月起	QPS 提升
路面气象预报	定制	中国路网 1 公里网格级
企业级	定制	电力、金融场景延迟 ≤15ms

💡 完整价格见 https://www.seniverse.com/buy

十、SDK 与示例代码

官方 SDK

心知天气提供封装好的 SDK，主要功能包括：

解决加密问题，支持加密或直接使用 key 调用 API
统一数据返回格式（可选）
错误处理
数据缓存（可选）

官方 SDK 陆续支持多种编程语言，目前已发布：

Node.js（支持 TypeScript） —— 官方 SDK
其他语言持续支持中

V4 调用示例

官方维护的多语言 V4 调用示例仓库：seniverse/seniverse-api-v4-demos

语言	路径
Python	`python/demo-jsonp.py`（签名验证示例）
Node.js	`nodejs/index.js`
Golang	`golang/main.go`
Java	`java/src/Example`

V3 多语言示例

V3 文档附带以下语言示例代码（详见开始使用）：

Node.js
Python
PHP
Android
JSONP
Swift

安全提醒

⚠️ 为了保证账号安全，不要纯前端进行 API 调用！纯前端调用会造成 uid 和 key 暴露。推荐方式：

后端进行 API 调用获取数据后交给前端渲染

或后端构造 JSONP 形式的请求链接，交给前端调用

十一、技术支持

渠道	信息
V4 文档	https://seniverse.yuque.com/hyper_data/api_v4/gniqvo
V3 文档	https://docs.seniverse.com/
帮助文档	http://docs.seniverse.com
客服电话	400-022-5889
客服邮箱	hi@seniverse.com（24 小时内回复）
客服 QQ 群	26381707
微信公众号	心知天气（扫描官网二维码添加客服）
知乎专栏	https://zhuanlan.zhihu.com/weather
GitHub	https://github.com/seniverse
ICP 备案	京ICP备16067076号

十二、V3 vs V4 主要差异

对比项	V3（持续维护）	V4（新版，推荐新项目）
API 端点	多路径（`/v3/weather/now.json`、`/v3/grid/now.json` 等）	单一端点（`/v4?fields=...`）
认证方式	私钥直接请求 / uid+key 签名	public_key + HMAC-SHA1 签名（强制）
数据格式	城市级（city-based）+ 公里级网格（grid）	网格级（grid-based）
位置参数	`location=beijing`（城市名 / ID / IP / 经纬度）	`locations=39.93:116.40`（仅经纬度）
定位精度	城市级 + 1×1 公里网格	公里级网格
私钥传输	直接方式可能出现在 URL 中	仅用于签名，不在网络中传输
接口分类	9 大类（天气/空气/生活/地理/功能/海洋/农业/图层/网格）	按 `fields` 切分，更扁平
新增能力	海洋类、农业类、气象图层（近期新增）	路面气象预报、台风列表
文档地址	https://docs.seniverse.com/	https://seniverse.yuque.com/hyper_data/api_v4/gniqvo

💡 选型建议：

新项目优先选择 V4 —— 安全性更高（强制签名）、端点扁平、覆盖全球网格

需要 城市级 API + 多语言 SDK + 完整生态 的项目可用 V3

需要 海洋 / 农业 / 气象图层 / 公里级网格历史 等垂直能力 → V3（V4 暂未覆盖）

需要 路面气象预报 / 全球台风 → V4

两者可在同一账号下并存，密钥体系独立

十三、常见问题

Q: 免费试用结束后还能用吗？

免费套餐不会自动到期，但 14 天全功能试用到期后，未付费的接口将停止响应。基础免费额度可在控制台查看。

Q: V4 API 返回 `{"status": "error"}` 怎么办？

检查以下原因：

公钥和私钥是否正确
签名计算是否正确（参数排序、HMAC-SHA1、Base64）
ts 时间戳是否与服务端时间偏差过大（建议使用 NTP 同步）
ttl 是否过短（建议至少 300 秒）
fields 参数值是否正确
参与签名的参数是否包含 ts、ttl（可选）、public_key 及业务参数
ts 和 ttl 的单位都是秒

Q: V3 直接 Key 调用为什么不行？

V3 允许直接 Key 调用，但出于安全考虑官方强烈不推荐纯前端调用。如必须在前端使用，应让后端构造 JSONP 形式的请求链接，由前端通过 JSONP 调用，避免密钥暴露。

Q: V4 API 支持哪些编程语言的 SDK？

心知天气官方在 GitHub 维护 V4 调用示例：seniverse/seniverse-api-v4-demos，覆盖 Node.js、Python、Golang、Java。官方 SDK 已发布 Node.js（支持 TypeScript）版本，其他语言持续支持中。

Q: V3 的老接口还能用吗？

V3 接口持续维护且仍在扩容（2025-2026 年新增海洋类、农业类、气象图层等），适合需要城市级 API 或 V4 暂未覆盖的垂直场景。新项目无特殊需求推荐直接使用 V4。

Q: 公里级网格数据覆盖范围？

V3 公里级网格（/v3/grid/*）覆盖中国地区，精度 1×1 公里。V4 网格数据覆盖全球。

Q: 如何获取技术支持？

详见十一、技术支持。优先渠道：客服电话 400-022-5889、邮箱 hi@seniverse.com、QQ 群 26381707。

免责声明: 本文档基于 2026 年 8 月公开信息整理，含官方文档（docs.seniverse.com、seniverse.yuque.com）与官网（seniverse.com）调研。心知天气可能随时调整套餐内容、价格、接口字段与文档地址，请以官网最新信息为准。