Daily Forecast

The daily forecast endpoint returns day-by-day forecasts for the requested location, including full-day/daytime/nighttime variables, air quality, life indices, and sunrise/sunset times.

Update Frequency and Spatial Resolution

Daily forecast data is cycle-based (typically 2-4 runs/day), has ~9-13 km spatial scale (aggregated from hourly data), and covers the next fifteen days daily. Life index data covers the next fifteen days daily. For details, see Variable Coverage.

Request

http

GET https://api.caiyunapp.com/v2.6/{token}/{longitude},{latitude}/daily

Path Parameters

Parameter	Description
`token`	API token; see Authentication
`longitude`	Longitude of the target location
`latitude`	Latitude of the target location

Note: in the URL path, longitude comes first, latitude second (e.g. -74,40.7); the location field in the response is in [latitude, longitude] order (e.g. [40.7, -74.0]).

Query Parameters

Name	Required	Default	Range	Description
`lang`	No	`zh_CN`	`zh_CN`/`zh_TW`/`en_US`/`en_GB`/`ja`/`ug`/`bo`	Language of natural-language descriptions; falls back to `zh_CN` when unmatched. See Languages
`unit`	No	`metric`	`metric`/`metric:v1`/`metric:v2`/`SI`/`imperial`	Unit system; any other value returns 422. See Units
`alert`	No	`false`	`true`/`false`	With `alert=true` and an alert-enabled token, the response includes `result.alert`. See Weather Alerts
`callback`	No	—	—	JSONP callback name
`dailysteps`	No	`5`	1~16	Number of days to return; normally 1~15, and `dailysteps=16` requires `dailystart=-1`. The effective limit depends on your plan, and requests beyond it are truncated to the plan's limit
`dailystart`	No	`0`	`-1`, `0`	Only -1 and 0 are supported (-1 goes back one day); any other value returns 422

Request Example

bash

curl "https://api.caiyunapp.com/v2.6/{token}/101.6656,39.2072/daily?dailysteps=1"

json

{
  "status": "ok",
  "api_version": "v2.6",
  "api_status": "active",
  "lang": "zh_CN",
  "unit": "metric",
  "tzshift": 28800,
  "timezone": "Asia/Shanghai",
  "server_time": 1653552787,
  "location": [
    39.2072,
    101.6656
  ],
  "result": {
    "daily": {
      "status": "ok",
      "astro": [
        {
          "date": "2022-05-26T00:00+08:00",
          "sunrise": {
            "time": "05:51"
          },
          "sunset": {
            "time": "20:28"
          }
        }
      ],
      "precipitation_08h_20h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 0,
          "min": 0,
          "avg": 0,
          "probability": 0
        }
      ],
      "precipitation_20h_32h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 0,
          "min": 0,
          "avg": 0,
          "probability": 0
        }
      ],
      "precipitation": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 0,
          "min": 0,
          "avg": 0,
          "probability": 0
        }
      ],
      "temperature": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 27,
          "min": 18,
          "avg": 23.75
        }
      ],
      "temperature_08h_20h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 27,
          "min": 18,
          "avg": 24.57
        }
      ],
      "temperature_20h_32h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 24.8,
          "min": 18,
          "avg": 20.02
        }
      ],
      "wind": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": {
            "speed": 28.24,
            "direction": 122.62
          },
          "min": {
            "speed": 9,
            "direction": 104
          },
          "avg": {
            "speed": 21.61,
            "direction": 118.02
          }
        }
      ],
      "wind_08h_20h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": {
            "speed": 28.24,
            "direction": 122.62
          },
          "min": {
            "speed": 9,
            "direction": 104
          },
          "avg": {
            "speed": 22.74,
            "direction": 115.78
          }
        }
      ],
      "wind_20h_32h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": {
            "speed": 22.39,
            "direction": 97.46
          },
          "min": {
            "speed": 9.73,
            "direction": 125.93
          },
          "avg": {
            "speed": 16,
            "direction": 121.62
          }
        }
      ],
      "humidity": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 0.18,
          "min": 0.08,
          "avg": 0.09
        }
      ],
      "cloudrate": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 1,
          "min": 0,
          "avg": 0.75
        }
      ],
      "pressure": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 84500.84,
          "min": 83940.84,
          "avg": 83991.97
        }
      ],
      "visibility": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 25,
          "min": 24.13,
          "avg": 25
        }
      ],
      "dswrf": [
        {
          "date": "2022-05-26T00:00+08:00",
          "max": 741.9,
          "min": 0,
          "avg": 368.6
        }
      ],
      "air_quality": {
        "aqi": [
          {
            "date": "2022-05-26T00:00+08:00",
            "max": {
              "chn": 183,
              "usa": 160
            },
            "avg": {
              "chn": 29,
              "usa": 57
            },
            "min": {
              "chn": 20,
              "usa": 42
            }
          }
        ],
        "pm25": [
          {
            "date": "2022-05-26T00:00+08:00",
            "max": 74,
            "avg": 15,
            "min": 10
          }
        ]
      },
      "skycon": [
        {
          "date": "2022-05-26T00:00+08:00",
          "value": "PARTLY_CLOUDY_DAY"
        }
      ],
      "skycon_08h_20h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "value": "PARTLY_CLOUDY_DAY"
        }
      ],
      "skycon_20h_32h": [
        {
          "date": "2022-05-26T00:00+08:00",
          "value": "CLOUDY"
        }
      ],
      "life_index": {
        "ultraviolet": [
          {
            "date": "2022-05-26T00:00+08:00",
            "index": "1",
            "desc": "Lowest"
          }
        ],
        "carWashing": [
          {
            "date": "2022-05-26T00:00+08:00",
            "index": "1",
            "desc": "Ideal"
          }
        ],
        "dressing": [
          {
            "date": "2022-05-26T00:00+08:00",
            "index": "4",
            "desc": "Warm"
          }
        ],
        "comfort": [
          {
            "date": "2022-05-26T00:00+08:00",
            "index": "4",
            "desc": "Warm"
          }
        ],
        "coldRisk": [
          {
            "date": "2022-05-26T00:00+08:00",
            "index": "4",
            "desc": "Highly Probable"
          }
        ]
      }
    },
    "primary": 0
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

Response Fields

JSONPath	Type	Description
`$.result.daily.temperature[]`	`array<object>`	Surface 2 m air temperature (whole day); each item contains `max`, `min`, and `avg`
`$.result.daily.temperature_08h_20h[]`	`array<object>`	Surface 2 m air temperature (daytime); each item contains `max`, `min`, and `avg`
`$.result.daily.temperature_20h_32h[]`	`array<object>`	Surface 2 m air temperature (nighttime); each item contains `max`, `min`, and `avg`
`$.result.daily.pressure[]`	`array<object>`	Surface pressure; each item contains `max`, `min`, and `avg`
`$.result.daily.humidity[]`	`array<object>`	Surface 2 m relative humidity (0-1); each item contains `max`, `min`, and `avg`
`$.result.daily.wind[]`	`array<object>`	Surface 10 m wind (whole day); each of `max`/`min`/`avg` contains `speed` and `direction`
`$.result.daily.wind_08h_20h[]`	`array<object>`	Surface 10 m wind (daytime); same structure as above
`$.result.daily.wind_20h_32h[]`	`array<object>`	Surface 10 m wind (nighttime); same structure as above
`$.result.daily.precipitation_08h_20h[]`	`array<object>`	Daytime precipitation; each item contains `max`, `min`, `avg`, and `probability`
`$.result.daily.precipitation_20h_32h[]`	`array<object>`	Nighttime precipitation; each item contains `max`, `min`, `avg`, and `probability`
`$.result.daily.precipitation[]`	`array<object>`	Whole-day precipitation; each item contains `max`, `min`, `avg`, and `probability`
`$.result.daily.cloudrate[]`	`array<object>`	Cloud cover (0.0-1.0); each item contains `max`, `min`, and `avg`
`$.result.daily.dswrf[]`	`array<object>`	Downward shortwave radiation flux (W/M2); each item contains `max`, `min`, and `avg`
`$.result.daily.visibility[]`	`array<object>`	Surface horizontal visibility; each item contains `max`, `min`, and `avg`
`$.result.daily.skycon[].value`	string	Dominant sky condition (whole day)
`$.result.daily.skycon_08h_20h[].value`	string	Dominant sky condition (daytime)
`$.result.daily.skycon_20h_32h[].value`	string	Dominant sky condition (nighttime)
`$.result.daily.life_index.ultraviolet[]`	`array<object>`	Ultraviolet index; `index` is a string from "0" to "5" (including "0" = none, at night); see Life Index for `desc`
`$.result.daily.life_index.comfort[]`	`array<object>`	Comfort index; `index` is a string from "0" to "13"; see Life Index for `desc`
`$.result.daily.life_index.carWashing[]`	`array<object>`	Car-washing index; `index` is a string from "1" to "4"; see Life Index for `desc`
`$.result.daily.life_index.coldRisk[]`	`array<object>`	Cold-risk index; `index` is a string from "1" to "4"; see Life Index for `desc`
`$.result.daily.life_index.dressing[]`	`array<object>`	Dressing index; `index` is a string from "0" to "8"; see Life Index for `desc`
`$.result.daily.air_quality.pm25[]`	`array<object>`	PM2.5 concentration (μg/m3); each item contains `max`, `min`, and `avg`
`$.result.daily.air_quality.aqi[]`	`array<object>`	AQI; each of `max`/`min`/`avg` contains `chn` and `usa`
`$.result.daily.astro[]`	`array<object>`	Sunrise/sunset times (local time of the location); each item contains `sunrise` and `sunset`

For xxx, xxx_08h_20h, xxx_20h_32h:

xxx means the whole day, 00:00-24:00
xxx_08h_20h means 08:00-20:00 of the day
xxx_20h_32h means 20:00 of the day to 08:00 of the next day

Notes:

For full-day variables, xxx.avg on the current day is the average from the current whole hour to the end of the day, not the average of the whole day; the exception is wind.avg (including direction), which is always the 24-hour average of the whole day.
xxx_08h_20h.avg and xxx_20h_32h.avg are always averages over the full 12-hour window; max/min are always extremes over the corresponding full time window.

Errors

Error responses have the following structure. See Error Messages for HTTP status codes and their meanings.

json

{
  "status": "failed",
  "error": "token is invalid",
  "api_version": "2.6"
}

Daily Forecast ​

Update Frequency and Spatial Resolution ​

Request ​

Path Parameters ​

Query Parameters ​

Request Example ​

Response Fields ​

Errors ​