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

From Caiyun Wiki
Jump to: navigation, search
(→‎API call examples)
 
(63 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
{{ColorfulClouds Weather API versions}}
 
{{ColorfulClouds Weather API versions}}
 +
 +
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 ==
 
== Authentication ==
Line 5: Line 7:
 
After signing up at '''[https://dashboard.caiyunapp.com/user/sign_up/ the dahsboard]''', you will get your access token. In below sections, we will use a temporary token for demo purpose: <code>S45Fnpxcwyq0QT4b</code>. In production or development, you should use your own.
 
After signing up at '''[https://dashboard.caiyunapp.com/user/sign_up/ the dahsboard]''', you will get your access token. In below sections, we will use a temporary token for demo purpose: <code>S45Fnpxcwyq0QT4b</code>. In production or development, you should use your own.
  
−
== API call by examples ==
+
== API request ==
  
−
=== Scenarios of weather apps ===
+
We support <code>json</code> and <code>jsonp</code>
  
−
* New York: Weather forecast for New York including real time condition, 2h minutely precipitation forecast, 48h hourly general forecast, 5d daily general forecast, in English and Imperial and US customary measurement systems.
+
* <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json</code>
−
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial</code>
+
* <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.jsonp&callback=CALLBACK</code>
−
* Tokyo: Weather forecast for Tokyo including real time condition, 2h minutely precipitation forecast, 48h hourly general forecast, 5d daily general forecast, in Japanese and Metric measurement system.
 
−
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja</code>
 
  
−
=== Scenarios of planning software ===
+
=== Parameters ===
  
−
* Short term: 24 hour hourly forecast
+
* '''lang''': optional, the language, default value is <code>zh_CN</code>, you can set any one of <code>zh_CN</code>, <code>zh_TW</code>, <code>en_US</code>, <code>en_GB</code>, <code>ja</code>
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US</code>
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja</code>
 +
* '''unit''': optional, the unit system, default value is <code>metric</code>, you can set any one of <code>metric</code>, <code>imperial</code>, <code>SI</code>
 
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial&granu=hourly&hourlysteps=24</code>
 
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial&granu=hourly&hourlysteps=24</code>
−
* Long term: 10 days daily forecast
+
* '''granu''': optional, the temporal granularity, default value is <code>realtime,minutely,hourly,daily</code>, you can set any one or combinations of <code>realtime</code>, <code>minutely</code>, <code>hourly</code>, <code>daily</code>
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.json?lang=en_US&unit=SI&granu=realtime</code>
 +
* '''hourlysteps''': optional, how many hours will be present in hourly forecast, default value is <code>48</code> hours and maximal value is <code>360</code> hours
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/172.0060,33.7128/weather.json?lang=en_US&unit=SI&granu=hourly&hourlysteps=12</code>
 +
 
 +
* '''dailysteps''': optional, how many days will be present in daily forecast, default value is <code>5</code> days and maximal value is <code>15</code> days
 
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja&granu=daily&dailysteps=10</code>
 
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja&granu=daily&dailysteps=10</code>
  
−
=== Scenarios of scientific instrument ===
+
== API response ==
 +
 
 +
To understand the API response better, you should know the control parameter <code>granu</code>and  all the variables.
 +
 
 +
=== 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 supported variables ===
 +
 
 +
All the supported variables are physical variables on or near earth's surface, please check [[{{FULLPAGENAME}}#Appendix: table of available weather variables|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 <code>skycon</code>
 +
 
 +
* skycon: it is a collection of short descriptive code of weather phenomenon on earth surface introduce by [https://darkskyapp.github.io/skycons/ 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.
 +
 
 +
<div style="float:right;text-align:right;margin:0em;margin-top:0.5em;padding:0.25em;background-color:tomato;">yaml</div>
 +
<syntaxhighlight lang="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
 +
</syntaxhighlight>
 +
 
 +
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 <code>realtime</code> is in <code>granu</code> parameters. It gives the estimation of real-time weather conditions.
  
−
* Assume an instrument on an ocean drilling ship need to get hourly data for next 12 hour
+
<div style="float:right;text-align:right;margin:0em;margin-top:0.5em;padding:0.25em;background-color:tomato;">yaml</div>
−
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/172.0060,33.7128/weather.json?lang=en_US&unit=SI&granu=hourly&hourlysteps=12</code>
+
<syntaxhighlight lang="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
 +
</syntaxhighlight>
 +
 
 +
=== The minutely part in result ===
  
−
=== Scenarios of real-time cases ===
+
This part of result will be show when <code>minutely</code> is in <code>granu</code> parameters. It is the minute-by-minute forecast for next 2 hours.
  
−
* Assume a drone control system need the current realtime weather data, but the data should be in SI unit system for convenience of control calculation.
+
<div style="float:right;text-align:right;margin:0em;margin-top:0.5em;padding:0.25em;background-color:tomato;">yaml</div>
−
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.json?lang=en_US&unit=SI&granu=realtime</code>
+
<syntaxhighlight lang="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
 +
</syntaxhighlight>
  
−
=== Scenarios of webapps ===
+
=== The hourly part in result ===
  
−
* with jsonp callback <code>check_weather</code>
+
This part of result will be show when <code>hourly</code> is in <code>granu</code> parameters. It is the hourly forecast for next several hours which is specified by parameter <code>hourlysteps</code>.
−
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.jsonp?lang=en_US&callback=check_weather</code>
 
  
−
== Parameters ==
+
<div style="float:right;text-align:right;margin:0em;margin-top:0.5em;padding:0.25em;background-color:tomato;">yaml</div>
 +
<syntaxhighlight lang="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
  
−
* '''lang''': optional, the language, default value is <code>zh_CN</code>, you can set any one of <code>zh_CN</code>, <code>zh_TW</code>, <code>en_US</code>, <code>en_GB</code>, <code>ja</code>
+
</syntaxhighlight>
−
* '''unit''': optional, the unit system, default value is <code>metric</code>, you can set any one of <code>metric</code>, <code>imperial</code>, <code>SI</code>
 
−
* '''granu''': optional, the temporal granularity, default value is <code>realtime,minutely,hourly,daily</code>, you can set any one or combinations of <code>realtime</code>, <code>minutely</code>, <code>hourly</code>, <code>daily</code>
 
−
* '''hourlysteps''': optional, how many hours will be present in hourly forecast, default value is <code>48</code> hours and maximal value is <code>360</code> hours
 
−
* '''dailysteps''': optional, how many days will be present in daily forecast, default value is <code>5</code> days and maximal value is <code>15</code> days
 
  
−
== Return values ==
+
=== The daily part in result ===
  
 +
This part of result will be show when <code>daily</code> is in <code>granu</code> parameters. It is the daily forecast for next several days which is specified by parameter <code>dailysteps</code>.
  
−
== Errors ==
+
<div style="float:right;text-align:right;margin:0em;margin-top:0.5em;padding:0.25em;background-color:tomato;">yaml</div>
 +
<syntaxhighlight lang="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
  
 +
</syntaxhighlight>
  
 
== Other links ==
 
== Other links ==
Line 55: Line 314:
 
* [[Supported measurement systems in ColorfulClouds Weather API]]
 
* [[Supported measurement systems in ColorfulClouds Weather API]]
 
* [[Datetime calculation in ColorfulClouds Weather API]]
 
* [[Datetime calculation in ColorfulClouds Weather API]]
 +
 +
== Appendix 1: table of available weather variables ==
 +
 +
{{:Table of available weather variables}}
 +
 +
 +
== Appendix 2: Data coverage ==
 +
 +
[[File:2020.3 彩云天气高精度数据覆盖范围.png|thumb|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.
 +
 +
{| class="wikitable"
 +
!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.
 +
 +
 +
[[zh-cn:通用预报接口/v2.5]]

Latest revision as of 07:19, 9 April 2020

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"