General weather interface/v2.5

From Caiyun Wiki
Jump to: navigation, search

Version of this article: v2.5，current stable version: v2.5，historical veriosns: v2.4

General weather interface v2.5 is part of ColorfulClouds Weather API, which gives the general pointwise weather forecast for a specific latitude and longitude.

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

Parameters

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, please check appendix below for detailed specification.

  • 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

Other links

Appendix 1: table of available weather variables

Name Code Quality Unit of measurement Temporal granularity Geospatial scope Comments
Temperature temperature temperature °C, °F, K realtime, hourly, daily globally temperature 2m above
Pressure pressure pressure Pa realtime, hourly, daily globally pressure on surface
Relative humidity humidity relative humidity  % realtime, hourly, daily globally relative humidity 2m above
Wind direction wind direction wind direction degree realtime, hourly, daily globally wind direction 10m above
Wind speed wind speed wind speed km/h, mph, m/h realtime, hourly, daily globally wind speed 10m above
Cloud rate cloudrate total cloud rate 0~1 realtime, hourly, daily globally total cloud rate
Shortwave radiation dswrf downward shortwave radiation W/m^2 realtime, hourly, daily globally downward shortwave radiation on surface
Visibility visibility visibility by distance km, mile, m realtime, hourly, daily globally horizontal visibility by distance on surface
Nearest distance to precipitation area Nearest distance to precipitation area distance km, mile, m realtime radar supported area nearest distance to precipitation area
Intensity of nearest precipitation intensity of nearest precipitation precipitation intensity 0~1 realtime radar supported area intensity of nearest precipitation
Intensity of local precipitation Intensity of local precipitation precipitation intensity 0~1 realtime, minutely radar supported area intensity of local precipitation
sky condition skycon weather condition text realtime, hourly, daily globally weather condition
comfort index comfort index comfort index text realtime, hourly, daily globally weather comfort condition
ultraviolet index ultraviolet index ultraviolet index text realtime, hourly, daily globally ultraviolet condition
PM25 pm25 PM25 μg/m^3 realtime, hourly, daily air-quality forecast supported area PM25 mass concentration
PM10 pm10 PM10 μg/m^3 realtime air-quality forecast supported area PM10 mass concentration
O3 o3 O3 μg/m^3 realtime air-quality forecast supported area O3 mass concentration
NO2 no2 No2 μg/m^3 realtime air-quality forecast supported area NO2 mass concentration
SO2 so2 SO2 μg/m^3 realtime air-quality forecast supported area SO2 mass concentration
CO co CO mg/m^3 realtime air-quality forecast supported area CO mass concentration
AQI aqi AQI by US and China standard 0~500 realtime, hourly, daily air-quality forecast supported area AQI by US and China standard


Appendix 2: Data coverage

Global coverage of minutely forecast

Data coverage of general weather forecast

  • Since the just begining of our weather API offering, we provide global hourly and daily weather forecast at any point on earth with arbitrary latitude and longitude.

Data coverage of minute-by-minute nowcasting service

We are among the few providers can give global-wide nowcasting service, we can provide service in below areas.

The quality of our nowcasting services is related with the quality of service of the radar data providers, it may vary from country to country; but as a service provider since 2014, we are a provened player in this area.

Continent Country/region
Europe Italy, Lithuania, Malta, France, Slovakia, Norway, Belarus, Iceland, Czech Republic, Slovenia, Germany, Spain, Ukraine, Denmark, Poland, Finland, Sweden, Croatia, Russia, Romania, Portugal, Estonia, Serbia, United Kingdom, Austria, Greece, Hungary
Oceania Fiji, Guam, Australia, Marshall Islands, New Caledonia, Australia
Asia Mainland China, Hong Kong, Macao and Taiwan, Diaoyu Islands, Spratly Islands, Turkey, Bahrain, Saudi Arabia, Indonesia, Iran, Singapore, Oman, Philippines, Japan, India, Cambodia, Cyprus, Malaysia, Vietnam, Kuwait, Thailand, South Korea, North Korea
North America Canada, Bahamas, Cayman Islands, Mexico, Panama, Martinique, Cuba, United States, Bermuda, Puerto Rico, Kura, Guadeloupe, Nicaragua
South America Brazil, French Guiana, Colombia, Guyana, Paraguay, Argentina

Data coverage of air quality forecast

Full scope of China.

Retrieved from "https://open.caiyunapp.com/index.php?title=General_weather_interface/v2.5&oldid=5910"