General weather interface/v2.5

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 calls by examples

Scenarios of weather apps

• 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.
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial
• 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.
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja

Scenarios of planning software

• Short term: 24 hour hourly forecast
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial&granu=hourly&hourlysteps=24
• Long term: 10 days daily forecast
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja&granu=daily&dailysteps=10

Scenarios of scientific instrument

• Assume an instrument on an ocean drilling ship need to get hourly data for next 12 hour
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/172.0060,33.7128/weather.json?lang=en_US&unit=SI&granu=hourly&hourlysteps=12

Scenarios of real-time cases

• 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.
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.json?lang=en_US&unit=SI&granu=realtime

Scenarios of webapps

• with jsonp callback check_weather
  • https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.jsonp?lang=en_US&callback=check_weather

Parameters

• lang: optional, the language, default value is zh_CN, you can set any one of zh_CN, zh_TW, en_US, en_GB, ja
• unit: optional, the unit system, default value is metric, you can set any one of metric, imperial, SI
• granu: optional, the temporal granularity, default value is realtime,minutely,hourly,daily, you can set any one or combinations of realtime, minutely, hourly, daily
• hourlysteps: optional, how many hours will be present in hourly forecast, default value is 48 hours and maximal value is 360 hours
• dailysteps: optional, how many days will be present in daily forecast, default value is 5 days and maximal value is 15 days

Return values

---
status: ok
api_version: v2.5
api_status: active
lang: en_US
unit: imperial
tzshift: -14400
timezone: America/New_York
server_time: 1585894300
location:
- 40.7128
- -74.006
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
  minutely:
    status: ok
    datasource: radar
    precipitation_2h:
    - 0.245
    - 0.2453
    - 0.2467
    precipitation:
    - 0.245
    - 0.2453
    - 0.2467
    probability:
    - 0.9703164364
    - 0.9908214629
    - 0.9060320288
    - 0
    description: " rain easing off in one hour"
  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
  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
  primary: 0
  forecast_keypoint: " rain easing off in one hour"

Other links

• Supported languages in ColorfulClouds Weather API
• Supported measurement systems in ColorfulClouds Weather API
• Datetime calculation in ColorfulClouds Weather API