Social Observation Service
Endpoint for submitting user feedback on current weather.
Request
http
GET https://api.caiyunapp.com/v1/social_observationQuery Parameters
| Name | Required | Default | Range | Description |
|---|---|---|---|---|
longitude | Yes | — | [-180, 180] | Longitude; missing or invalid values return 422 |
latitude | Yes | — | [-90, 90] | Latitude; missing or invalid values return 422 |
main_info | Yes | — | 0~7, see Primary Weather Types | Primary weather type code. The backend does not validate enum values, but a missing or non-numeric value returns 500, so use the table below |
sub_info | Yes | — | type,level, see Secondary Weather Types | Secondary weather type, comma-separated (only the first two segments are used). The backend does not validate enum values |
user_id | No | — | — | User ID; third-party partners may hash it before providing it to Caiyun. When missing, it is recorded as null and the request still succeeds |
token | Yes | — | — | API token; see Authentication. Access to this endpoint must be granted separately, otherwise 401 unauthorized token is returned |
callback | No | — | — | JSONP output |
Request Example
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}"Primary Weather Types
| Name | Code |
|---|---|
| Clear | 0 |
| Partly Cloudy | 1 |
| Overcast | 2 |
| Rain | 3 |
| Snow | 4 |
| Haze | 5 |
| Wind | 6 |
| Icing | 7 |
Secondary Weather Types
| Name | Code | Level | Description |
|---|---|---|---|
| Cloud Cover | 0 | 0 | Not a cloud in the sky |
| 1 | A few wisps of thin cloud | ||
| 2 | Tufts of cotton-like cloud | ||
| 3 | Clouds blotting out the sky | ||
| 4 | Dark clouds across the sky | ||
| Rainfall | 1 | 0 | Scattered light rain |
| 1 | Pattering drizzle | ||
| 3 | Pouring rain | ||
| 5 | Flooding rainstorm | ||
| Snowfall | 2 | 0 | Barely noticeable |
| 1 | Scattered flurries | ||
| 2 | Falling snowflakes | ||
| 3 | Heavy goose-feather snow | ||
| 4 | Blizzard | ||
| Visibility | 3 | 1 | Slight mist |
| 3 | Impaired visibility | ||
| 5 | Dense fog | ||
| Thunder | 4 | 5 | Lightning and thunder |
| 6 | Thunderstorm | ||
| Hail | 5 | 5 | Hailstorm incoming |
| Sand | 6 | 1 | Haze invasion |
| 3 | Raging sandstorm | ||
| Wind | 7 | 0 | No wind |
| 1 | Breeze | ||
| 5 | Strong wind | ||
| 9 | Howling gale | ||
| 20 | Tornado | ||
| Icing | 8 | 1 | Roadside icing |
Response
On success:
json
{ "status": "ok" }Response Fields
| JSONPath | Type | Description |
|---|---|---|
$.status | string | Request status: ok or failed |
$.msg | string | Failure reason, returned on failure |
Errors
On failure:
json
{ "status": "failed", "msg": "..." }HTTP status codes:
| Status | Meaning |
|---|---|
| 400 | Invalid signature or token |
| 401 | Token has not been granted access to this endpoint |
| 403 | Token disabled, or IP not in the whitelist |
| 422 | Invalid parameters |
| 429 | QPS rate limited |
| 500 | Other errors |
Notes
- The endpoint is rate-limited per token.
- Each request synchronously fetches realtime weather for correction; an upstream failure may also return 500.
Caiyun App Client Presets
| Weather Phenomenon | main_info | sub_info code | sub_info level |
|---|---|---|---|
| Clear | 0 | 0 | 0 |
| Cloud/Few Clouds | 2 | 0 | 1 |
| Cloud/Partly Cloudy | 2 | 0 | 2 |
| Cloud/Overcast | 2 | 0 | 3 |
| Rain/Light Rain | 3 | 1 | 1 |
| Rain/Moderate Rain | 3 | 1 | 2 |
| Rain/Heavy Rain | 3 | 1 | 3 |
| Snow/Sleet | 3 | 2 | 1 |
| Snow/Light Snow | 4 | 2 | 1 |
| Snow/Moderate Snow | 4 | 2 | 2 |
| Snow/Heavy Snow | 4 | 2 | 3 |
| Haze & Sand/Fog | 5 | 3 | 5 |
| Haze & Sand/Haze | 5 | 6 | 1 |
| Haze & Sand/Sandstorm | 5 | 6 | 3 |
| Lightning | 3 | 4 | 5 |
| Thunderstorm | 3 | 4 | 6 |
| Hail | 3 | 5 | 5 |
| Strong Wind | 6 | 7 | 5 |
| Tornado | 6 | 7 | 20 |
| Icing | 7 | 8 | 1 |