Difference between revisions of "General weather interface/v2.5"

From Caiyun Wiki
Jump to: navigation, search
(→‎API response)
(→‎Parameter granu in request)
Line 51: Line 51:
 
=== Parameter <code>granu</code> in request ===
 
=== Parameter <code>granu</code> in request ===
  
 +
<code>granu</code> 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 <code>realtime,minutely,hourly,daily</code>, and you can set any one or a combinations of below four code: <code>realtime</code>, <code>minutely</code>, <code>hourly</code>, <code>daily</code>.
  
 
=== The heading part ===
 
=== The heading part ===

Revision as of 21:58, 7 April 2020

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

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 all the variables and the control parameter granu.

The supported variables

All the supported variables are physical variables on or near earth's surface

  • temperature
  • precipitation: a group of variables
  • wind: speed and direction
  • humidity: relative humidity
  • pressure
  • 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.

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 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, 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

yaml
result:
  realtime:
    status: ok
    temperature: 46.92
    humidity: 0.6
    cloudrate: 0.99
    skycon: LIGHT_RAIN
    visibility: 14.99
    dswrf: 0
    wind:
      speed: 20.04
      direction: 327.03
    pressure: 100027.48
    apparent_temperature: 52.9
    precipitation:
      local:
        status: ok
        datasource: radar
        intensity: 0.245
      nearest:
        status: ok
        distance: 0
        intensity: 6
    air_quality:
      pm25: 0
      pm10: 0
      o3: 0
      so2: 0
      no2: 0
      co: 0
      aqi:
        chn: 0
        usa: 0
      description:
        usa: ''
        chn: missing
    life_index:
      ultraviolet:
        index: 0
        desc: None
      comfort:
        index: 2
        desc: Very hot

The minutely part in result

yaml
result:
  minutely:
    status: ok
    datasource: radar
    precipitation_2h:
    - 0.245
    precipitation:
    - 0.245
    probability:
    - 0.9703164364
    description: " rain easing off in one hour"

The hourly part in result

yaml
result:
  hourly:
    status: ok
    description: drizzle, expect rain to stop after 9 o'clock this morning, followed
      by overcast, then drizzle
    precipitation:
    - datetime: 2020-04-03T02:00-04:00
      value: 0.021
    temperature:
    - datetime: 2020-04-03T02:00-04:00
      value: 46.92
    wind:
    - datetime: 2020-04-03T02:00-04:00
      speed: 20.04
      direction: 327.03
    humidity:
    - datetime: 2020-04-03T02:00-04:00
      value: 0.6
    skycon:
    - datetime: 2020-04-03T02:00-04:00
      value: LIGHT_RAIN
    pressure:
    - datetime: 2020-04-03T02:00-04:00
      value: 100027.4809084723
    visibility:
    - datetime: 2020-04-03T02:00-04:00
      value: 14.99
    dswrf:
    - datetime: 2020-04-03T02:00-04:00
      value: 0
    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

yaml
result:
  daily:
    status: ok
    astro:
    - date: 2020-04-03T00:00-04:00
      sunrise:
        time: '06:34'
      sunset:
        time: '19:23'
    precipitation:
    - date: 2020-04-03T00:00-04:00
      max: 0.028
      min: 0
      avg: 0.0075
    temperature:
    - date: 2020-04-03T00:00-04:00
      max: 51.35
      min: 46.92
      avg: 49.74
    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:
    - date: 2020-04-03T00:00-04:00
      max: 0.76
      min: 0.57
      avg: 0.71
    cloudrate:
    - date: 2020-04-03T00:00-04:00
      max: 1
      min: 0.95
      avg: 1
    pressure:
    - date: 2020-04-03T00:00-04:00
      max: 100814.14
      min: 99934.41
      avg: 100305.84
    visibility:
    - date: 2020-04-03T00:00-04:00
      max: 14.99
      min: 9.67
      avg: 12.62
    dswrf:
    - date: 2020-04-03T00:00-04:00
      max: 138.9
      min: 0
      avg: 41.4
    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
    skycon:
    - date: 2020-04-03T00:00-04:00
      value: LIGHT_RAIN
    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=5840"