General weather interface/v2.5
Version of this article: v2.5，current stable version: v2.5，historical veriosns: v2.4
Contents
Authentication
After signing up at the dahsboard, you will get your access token. In below sections, we will use a temporary token for demo purpose: S45Fnpxcwyq0QT4b. In production or development, you should use your own.
API request
We support json and jsonp
-
https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json -
https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.jsonp&callback=CALLBACK
Parameters
- lang: optional, the language, default value is
zh_CN, you can set any one ofzh_CN,zh_TW,en_US,en_GB,ja - unit: optional, the unit system, default value is
metric, you can set any one ofmetric,imperial,SI - granu: optional, the temporal granularity, default value is
realtime,minutely,hourly,daily, you can set any one or combinations ofrealtime,minutely,hourly,daily - hourlysteps: optional, how many hours will be present in hourly forecast, default value is
48hours and maximal value is360hours
- dailysteps: optional, how many days will be present in daily forecast, default value is
5days and maximal value is15days
API response
To understand the API response better, you should know the control parameter granuand all the variables.
Parameter granu in request
granu is a short code for temporal granularity, it is the request parameter to control which part of data will show in the result. The default value is realtime,minutely,hourly,daily, and you can set any one or a combinations of below four code: realtime, minutely, hourly, daily.
The supported variables
All the supported variables are physical variables on or near earth's surface
- temperature
- precipitation: a group of variables specified below
- wind: speed and direction
- humidity: relative humidity
- pressure
- cloud coverage
- visibility: horizontal visibility on earth's surface
- dswrf: downward shortwave radiation flux
- air quality group: including aqi, pm25 and others
- life index group: indicators for comfort or not, or status of ultraviolet radiation
and also skycon
- skycon: it is a collection of short descriptive code of weather phenomenon on earth surface introduce by DarkSky and was released into public domain.
The heading part
The heading part gives you basic settings of the API response, it is the start point of any weather calculation.
yaml
status: ok # API response status
api_version: v2.5 # API version
api_status: active # API status: alpha, beta, stable, active, deprecated
lang: en_US # The i18n language parameter in response, supported languages are include en_US, en_GB, zh_CN, zh_TW, ja
unit: imperial # The i18n unit parameter in response, supported unit system are include metric, imperial and SI
tzshift: -14400 # Timezone shift measured in seconds
timezone: America/New_York # Timezone
server_time: 1585894300 # Server time measured in unix timestamp or total seconds from 1970-01-01 00:00:00
location:
- 40.7128 # The requested latitude
- -74.006 # The requested longitude
You should notice that this API are latitude-longitude based, we do not support city-based queries.
The real-time part in result
This part of result will be show when realtime is in granu parameters. It gives the estimation of real-time weather conditions.
yaml
result:
realtime:
status: ok
skycon: LIGHT_RAIN # Skycon
temperature: 46.92 # Temperature
apparent_temperature: 52.9 # Apparent temperature
precipitation:
local:
status: ok
datasource: radar # Data source for this precipitation calculation
intensity: 0.245 # Precipitation intensity
nearest:
status: ok
distance: 0 # Distance to the nearest precipitation area
intensity: 0.245 # Precipitation intensity of the nearest
wind:
speed: 20.04 # Wind speed
direction: 327.03 # Wind direction in degrees, north is zero
humidity: 0.6 # Relative humidity
pressure: 100027.48 # Pressure of the atmosphere
cloudrate: 0.99 # Cloud coverage
visibility: 14.99 # Horizontal visibility
dswrf: 0 # Downward shortwave radiation flux
air_quality:
pm25: 0
pm10: 0
o3: 0
so2: 0
no2: 0
co: 0
aqi:
chn: 0 # AQI by China standard
usa: 0 # AQI by USA standard
description:
usa: ''
chn: missing
life_index:
ultraviolet:
index: 0
desc: None
comfort:
index: 2
desc: Very hot
The minutely part in result
This part of result will be show when minutely is in granu parameters. It is the minute-by-minute forecast for next 2 hours.
yaml
result:
minutely:
status: ok
datasource: radar # The datasource of the forecast
description: "rain easing off in one hour" # The featured natural language description of the weather conditions in next 2 hours
probability:
- 0.9703164364 # The probability of precipitation-happening in next 00~30 minutes
- 0.6687932653 # The probability of precipitation-happening in next 30~60 minutes
- 0.0294856625 # The probability of precipitation-happening in next 60~90 minutes
- 0.0 # The probability of precipitation-happening in next 90~120 minutes
precipitation_2h:
- 0.245 # The forecasted precipitation values for next 2 hours
- ... # Totally 120 data items
precipitation:
- 0.245 # The forecasted precipitation values for next 1 hour
- ... # Totally 60 data items
The hourly part in result
This part of result will be show when hourly is in granu parameters. It is the hourly forecast for next several hours which is specified by parameter hourlysteps.
yaml
result:
hourly:
status: ok
description: drizzle, expect rain to stop # The featured natural language description for next 24 hours.
after 9 o'clock this morning, followed
by overcast, then drizzle
skycon: # Skycon
- datetime: 2020-04-03T02:00-04:00 # The date time of a data slot, which belong to Skycon
value: LIGHT_RAIN # The value of a data slot, which gives the value of skycon for datetime 2020-04-03T02:00-04:00
temperature: # Temperature
- datetime: 2020-04-03T02:00-04:00
value: 46.92
precipitation: # Precipitation
- datetime: 2020-04-03T02:00-04:00
value: 0.021
wind: # Wind
- datetime: 2020-04-03T02:00-04:00
speed: 20.04
direction: 327.03
humidity: # Relative humidity
- datetime: 2020-04-03T02:00-04:00
value: 0.6
pressure: # Pressure
- datetime: 2020-04-03T02:00-04:00
value: 100027.4809084723
cloudrate: # Cloud coverage
- datetime: 2020-04-03T02:00-04:00
value: 0.90
visibility: # Horizontal visibility on earth's surface
- datetime: 2020-04-03T02:00-04:00
value: 14.99
dswrf: # Downward shortwave radiation flux on earth's surface
- datetime: 2020-04-03T02:00-04:00
value: 0
air_quality: # Air quality
aqi:
- datetime: 2020-04-03T02:00-04:00
value:
chn: 0
usa: 0
pm25:
- datetime: 2020-04-03T02:00-04:00
value: 0
The daily part in result
This part of result will be show when daily is in granu parameters. It is the daily forecast for next several days which is specified by parameter dailysteps.
yaml
result:
daily:
status: ok
astro:
- date: 2020-04-03T00:00-04:00
sunrise:
time: '06:34' # Sun rise time
sunset:
time: '19:23' # Sun set time
skycon: # Skycon
- date: 2020-04-03T00:00-04:00 # The date of this data slot
value: LIGHT_RAIN # Skycon value of date 2020-04-03
temperature: # Temperature
- date: 2020-04-03T00:00-04:00 # The date of this data slot
max: 51.35 # The maximal temperature of date 2020-04-03
min: 46.92 # The minimal temperature of date 2020-04-03
avg: 49.74 # The average temperature of date 2020-04-03
precipitation: # Precipitation
- date: 2020-04-03T00:00-04:00
max: 0.028
min: 0
avg: 0.0075
wind: # Wind
- date: 2020-04-03T00:00-04:00
max:
speed: 20.04
direction: 327.03
min:
speed: 13.17
direction: 12.79
avg:
speed: 16.85
direction: 347.62
humidity: # Humidity
- date: 2020-04-03T00:00-04:00
max: 0.76
min: 0.57
avg: 0.71
cloudrate: # Cloud coverage
- date: 2020-04-03T00:00-04:00
max: 1
min: 0.95
avg: 1
pressure: # Pressure
- date: 2020-04-03T00:00-04:00
max: 100814.14
min: 99934.41
avg: 100305.84
visibility: # Horizontal visibility
- date: 2020-04-03T00:00-04:00
max: 14.99
min: 9.67
avg: 12.62
dswrf: # Downward shortwave radiation flux on earth's surface
- date: 2020-04-03T00:00-04:00
max: 138.9
min: 0
avg: 41.4
air_quality: # Air quality
aqi:
- date: 2020-04-03T00:00-04:00
max:
chn: 0
usa: 0
avg:
chn: 0
usa: 0
min:
chn: 0
usa: 0
pm25:
- date: 2020-04-03T00:00-04:00
max: 0
avg: 0
min: 0
life_index: # Life index
ultraviolet:
- date: 2020-04-03T00:00-04:00
index: '1'
desc: Weak
carWashing:
- date: 2020-04-03T00:00-04:00
index: '3'
desc: Less appropriate
dressing:
- date: 2020-04-03T00:00-04:00
index: '2'
desc: Very hot
comfort:
- date: 2020-04-03T00:00-04:00
index: '0'
desc: Sticky hot
coldRisk:
- date: 2020-04-03T00:00-04:00
index: '3'
desc: Prone
