社会化观测服务
上报用户当前天气反馈的接口。
请求
http
GET https://api.caiyunapp.com/v1/social_observation查询参数
| 参数 | 必填 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|---|
longitude | 是 | — | [-180, 180] | 经度；缺失或非法返回 422 |
latitude | 是 | — | [-90, 90] | 纬度；缺失或非法返回 422 |
main_info | 是 | — | 0~7，见 主要天气类型 | 主要天气类型编码；后端不校验枚举取值，但缺失或非数字会返回 500，务必按表传值 |
sub_info | 是 | — | type,level，见 次要天气类型 | 次要天气类型，逗号分隔（多于两段时仅取前两段）；后端不校验枚举取值 |
user_id | 否 | — | — | 用户标识 ID，第三方合作伙伴可经过哈希算法等处理后提供；缺失时以 null 记录，请求照常成功 |
token | 是 | — | — | API 认证凭证，需单独开通本接口的访问权限（否则返回 401），详见 认证与鉴权 |
callback | 否 | — | — | JSONP 输出 |
请求示例
bash
curl "https://api.caiyunapp.com/v1/social_observation?longitude=116.364552&latitude=39.995280&main_info=0&sub_info=0,0&user_id={user_id}&token={token}"主要天气类型
| 名称 | 编码 |
|---|---|
| 晴 | 0 |
| 多云 | 1 |
| 阴 | 2 |
| 雨 | 3 |
| 雪 | 4 |
| 雾霾 | 5 |
| 大风 | 6 |
| 结冰 | 7 |
次要天气类型
| 名称 | 编码 | 级别 | 描述 |
|---|---|---|---|
| 云量 | 0 | 0 | 万里无云 |
| 1 | 几缕薄云 | ||
| 2 | 几坨棉花 | ||
| 3 | 遮天蔽日 | ||
| 4 | 乌云满天 | ||
| 雨量 | 1 | 0 | 零星小雨 |
| 1 | 淅淅沥沥 | ||
| 3 | 雨水如注 | ||
| 5 | 暴雨成灾 | ||
| 雪量 | 2 | 0 | 似有似无 |
| 1 | 零星小雪 | ||
| 2 | 飘落雪花 | ||
| 3 | 鹅毛大雪 | ||
| 4 | 暴雪纷飞 | ||
| 能见度 | 3 | 1 | 稍有薄雾 |
| 3 | 视线受阻 | ||
| 5 | 大雾 | ||
| 雷 | 4 | 5 | 电闪雷鸣 |
| 6 | 雷暴 | ||
| 冰雹 | 5 | 5 | 冰雹来袭 |
| 沙 | 6 | 1 | 雾霾侵袭 |
| 3 | 沙尘肆掠 | ||
| 风 | 7 | 0 | 无风 |
| 1 | 微风 | ||
| 5 | 风力强劲 | ||
| 9 | 狂风呼啸 | ||
| 20 | 龙卷风 | ||
| 结冰 | 8 | 1 | 路边结冰 |
响应
成功时返回：
json
{ "status": "ok" }响应字段
| JSONPath | 类型 | 说明 |
|---|---|---|
$.status | string | 请求状态：ok 或 failed |
$.msg | string | 失败原因，仅失败时返回 |
错误
失败时返回：
json
{ "status": "failed", "msg": "..." }HTTP 状态码含义：
| Status | 含义 |
|---|---|
| 400 | 签名或 token 无效 |
| 401 | token 未开通本接口的访问权限 |
| 403 | token 被禁用、IP 不在白名单 |
| 422 | 参数非法 |
| 429 | QPS 限流 |
| 500 | 其他异常 |
备注
- 接口按 token 限流。
- 每次请求会同步获取实时天气用于校正，上游异常时也可能返回 500。
彩云 App 客户端预设
| 天气现象 | main_info | sub_info 编码 | sub_info 级别 |
|---|---|---|---|
| 晴 | 0 | 0 | 0 |
| 云/少云 | 2 | 0 | 1 |
| 云/多云 | 2 | 0 | 2 |
| 云/阴 | 2 | 0 | 3 |
| 雨/小雨 | 3 | 1 | 1 |
| 雨/中雨 | 3 | 1 | 2 |
| 雨/大雨 | 3 | 1 | 3 |
| 雪/雨夹雪 | 3 | 2 | 1 |
| 雪/小雪 | 4 | 2 | 1 |
| 雪/中雪 | 4 | 2 | 2 |
| 雪/大雪 | 4 | 2 | 3 |
| 雾霾沙尘/雾 | 5 | 3 | 5 |
| 雾霾沙尘/霾 | 5 | 6 | 1 |
| 雾霾沙尘/沙尘暴 | 5 | 6 | 3 |
| 闪电 | 3 | 4 | 5 |
| 雷暴 | 3 | 4 | 6 |
| 冰雹 | 3 | 5 | 5 |
| 大风 | 6 | 7 | 5 |
| 龙卷 | 6 | 7 | 20 |
| 结冰 | 7 | 8 | 1 |