General weather interface/v2.5

From Caiyun Wiki
Revision as of 02:53, 9 April 2020 by Mingli (talk | contribs)
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

  • 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

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