Difference between revisions of "ColorfulClouds Weather API"

From Caiyun Wiki
Jump to: navigation, search
(The reliable and stable backend)
(Appendix 2: table of available variables)
 
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
== Try out by yourself ==
 
== Try out by yourself ==
  
<code>S45Fnpxcwyq0QT4b</code> is a demo token,in producation and development, you should use your own token after signing up at '''[https://dashboard.caiyunapp.com/user/sign_up/ the dahsboard]'''
+
<code>S45Fnpxcwyq0QT4b</code> is a demo token,in production and development, you should use your own token after signing up at '''[https://dashboard.caiyunapp.com/user/sign_up/ the dahsboard]'''
* [[General weather API interface/v2.5|General weather API interface]]<code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/121.6544,25.1552/weather.json</code>
+
 
 +
* [[General weather interface/v2.5|General weather interface]]
 +
** New York: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0060,40.7128/weather.json?lang=en_US&unit=imperial</code>
 +
 
 +
The quota of the demo token is very limited and is renewed periodically, so please only use it for testing. If you meet any problem to access the above link, please contact us at [mailto:api@caiyunapp.com api@caiyunapp.com]
 +
 
 +
== Contact us ==
 +
 
 +
Email: [mailto:api@caiyunapp.com api@caiyunapp.com]
 +
 
 +
== Business Scenarios ==
 +
 
 +
ColorfulClouds Weather API is carefully designed for different scenarios.
 +
 
 +
=== Weather apps ===
 +
 
 +
[[File:SmartphoneApp.jpg|235px|right|thumb|Weather apps]]
 +
 
 +
'''The hyperlocal feature''':
 +
 
 +
* Union Square, San Francisco in next 2 hr: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-122.4075,37.7879/weather.json?lang=en_US&granu=minutely</code>
 +
 
 +
'''Global availability''':
 +
 
 +
* Kathmandu: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/85.3240,27.7172/weather.json?lang=en_US&unit=imperial</code>
 +
* Frankfurt: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/8.6821,50.1109/weather.json?lang=en_US&unit=imperial</code>
 +
* New York: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-74.0059,40.7128/weather.json?lang=en_US&unit=imperial</code>
 +
* Hawaii: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.json?lang=en_US&unit=imperial</code>
 +
* Sydney: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/151.2093,-33.8688/weather.json?lang=en_US&unit=imperial</code>
 +
* Cape Town: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/18.4241,-33.9249/weather.json?lang=en_US&unit=imperial</code>
 +
 
 +
[[File:Autumn Drone.jpg|235px|right|thumb|Drone controlling]]
 +
 
 +
'''Supported languages''':
 +
 
 +
* Tokyo: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja</code>
 +
* Beijing: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/116.4074,39.9042/weather.json?lang=zh_CN</code>
 +
 
 +
'''Different unit systems''':
 +
 
 +
* Paris: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/2.3522,48.8566/weather.json?lang=en_US&unit=metric</code>
 +
* Sydney: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/151.2093,-33.8688/weather.json?lang=en_US&unit=imperial</code>
 +
 
 +
'''Sun rise and set time''':
 +
 
 +
* London: <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/0.1278,51.5074/weather.json?lang=en_US&granu=daily&fields=astro</code>
 +
 
 +
=== System control & IoT scenarios ===
 +
 
 +
In system control scenarios, it is very convenient to set the unit system to SI for calculation, and in many case you only need real-time data, so you can call the API in such a way
 +
 
 +
* <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.json?lang=en_US&unit=SI&granu=realtime</code>
 +
 
 +
=== Planning scenarios ===
 +
 
 +
* Short term: 24 hour hourly forecast
 +
** <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
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/139.7690,35.6804/weather.json?lang=ja&granu=daily&dailysteps=10</code>
 +
 
 +
=== Web applications ===
 +
 
 +
To integrate with a third party data, you need the '''jsonp''' support
 +
* with jsonp callback <code>check_weather</code>
 +
** <code>https://api.caiyunapp.com/v2.5/S45Fnpxcwyq0QT4b/-157.8583,21.3069/weather.jsonp?lang=en_US&callback=check_weather</code>
 +
 
  
 
== A global service ==
 
== A global service ==
  
[[File:Caiyun Intro.006.jpeg|thumb|right|A global service]]
 
 
[[File:2020.3 彩云天气高精度数据覆盖范围.png|thumb|Global coverage of minutely forecast]]
 
[[File:2020.3 彩云天气高精度数据覆盖范围.png|thumb|Global coverage of minutely forecast]]
  
 
=== Internationalization ===
 
=== Internationalization ===
  
* the datetime calculation will impact the avg/max/min value calculation of weather variables, our i18n features fully support this.
+
* the datetime calculation will impact the avg/max/min values of weather variables, our i18n features fully support this.
 
* the unit of measurement is fully support i18n requirement, we support [https://en.wikipedia.org/wiki/Metric_system Metric system], [https://en.wikipedia.org/wiki/Imperial_and_US_customary_measurement_systems Imperial and US customary units] and [https://en.wikipedia.org/wiki/International_System_of_Units International System of Units]
 
* the unit of measurement is fully support i18n requirement, we support [https://en.wikipedia.org/wiki/Metric_system Metric system], [https://en.wikipedia.org/wiki/Imperial_and_US_customary_measurement_systems Imperial and US customary units] and [https://en.wikipedia.org/wiki/International_System_of_Units International System of Units]
 
* the user-friendly nature language description of current weather conditions is support i18n, but we only provide Chinese, English and Japanese support.
 
* the user-friendly nature language description of current weather conditions is support i18n, but we only provide Chinese, English and Japanese support.
 
  
 
=== Data coverage of general weather forecast ===
 
=== Data coverage of general weather forecast ===
Line 22: Line 85:
 
=== Data coverage of minute-by-minute nowcasting service  ===
 
=== 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
+
We are among the few providers can give global-wide nowcasting service, we can provide service in [[{{FULLPAGENAME}}#Appendix 1: table of countries that nowcasting is supported|below areas]].
 
 
{| 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
 
|}
 
  
 
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.
 
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.
Line 48: Line 91:
 
=== Data coverage of air quality forecast ===
 
=== Data coverage of air quality forecast ===
  
Full scope of China and US.
+
Full scope of China.
  
 
== API Features ==
 
== API Features ==
Line 54: Line 97:
 
=== Full-scoped variables ===
 
=== Full-scoped variables ===
  
{| class="wikitable"
+
You can check a detailed table of [[{{FULLPAGENAME}}#Appendix 2: table of available variables|the supported 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
 
| pres || 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 || [[{{FULLPAGENAME}}#Coverage_of_minute-by-minute_nowcasting_service|radar supported area]] || nearest distance to precipitation area
 
|-
 
! Intensity of nearest precipitation
 
| intensity of nearest precipitation || precipitation intensity || 0~1 || realtime || [[{{FULLPAGENAME}}#Coverage_of_minute-by-minute_nowcasting_service|radar supported area]] || intensity of nearest precipitation
 
|-
 
! Intensity of local precipitation
 
| Intensity of local precipitation || precipitation intensity || 0~1 || realtime, minutely || [[{{FULLPAGENAME}}#Coverage_of_minute-by-minute_nowcasting_service|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 || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || PM25 mass concentration
 
|-
 
! PM10
 
| pm10 || PM10 || μg/m^3 || realtime || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || PM10 mass concentration
 
|-
 
! O3
 
| o3 || O3 || μg/m^3 || realtime || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || O3 mass concentration
 
|-
 
! NO2
 
| no2 || No2 || μg/m^3 || realtime || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || NO2 mass concentration
 
|-
 
! SO2
 
| so2 || SO2 || μg/m^3 || realtime || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || SO2 mass concentration
 
|-
 
! CO
 
| co || CO || mg/m^3 || realtime || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || CO mass concentration
 
|-
 
! AQI
 
| aqi || AQI by China standard || 0~500 || realtime, hourly, daily || [[{{FULLPAGENAME}}#Coverage_of_air_quality_forecast|air-quality forecast supported area]] || AQI by China standard
 
|}
 
  
 
=== The nowcasting service  ===
 
=== The nowcasting service  ===
 +
 +
We provide two kind of nowcasting service:
 +
 +
* pointwise API calls specified by latitude and longitude
 +
* forecasted weather radar images and forecasted data matrix
  
 
== The AI technology behind ==
 
== The AI technology behind ==
  
 
Since the founding at 2014, we always dedicated in improving the algorithms for years, there are many works behind the services.
 
Since the founding at 2014, we always dedicated in improving the algorithms for years, there are many works behind the services.
 
  
 
{| style="margin-left: auto; margin-right: auto; border: none;"
 
{| style="margin-left: auto; margin-right: auto; border: none;"
Line 159: Line 119:
 
== The reliable and stable backend ==
 
== The reliable and stable backend ==
  
* Scalability: the public service pool can offer 300M ~ 800M API calls per day and can scale up on demanding
+
* Scalability: the public service pool can offer 300M ~ 800M API calls per day and can be scaled up easily on demanding
 
* Availability: the availability of the public service pool for the past year is at 99.94%
 
* Availability: the availability of the public service pool for the past year is at 99.94%
 
We can offer private service pool with better availability for large-demanding clients
 
  
 
{| style="margin-left: auto; margin-right: auto; border: none;"
 
{| style="margin-left: auto; margin-right: auto; border: none;"
Line 169: Line 127:
 
| [[File:Caiyun Intro.016.jpeg|thumb|the technical architecture behind]]
 
| [[File:Caiyun Intro.016.jpeg|thumb|the technical architecture behind]]
 
|}
 
|}
 +
 +
We can offer private service pool with better availability for large-demanding clients
  
 
== The team behind ==
 
== The team behind ==
 
  
 
{| style="margin-left: auto; margin-right: auto; border: none;"
 
{| style="margin-left: auto; margin-right: auto; border: none;"
Line 179: Line 138:
 
|}
 
|}
  
== Contact us ==
+
 
 +
== Appendix 1: table of countries that nowcasting is supported ==
 +
 
 +
{| 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
 +
|}
 +
 
 +
 
 +
== Appendix 2: table of available weather variables ==
 +
 
 +
{{:Table of available weather variables}}
 +
 
 +
 
 +
[[zh-cn:彩云天气 API]]

Latest revision as of 02:50, 9 April 2020

Try out by yourself

S45Fnpxcwyq0QT4b is a demo token,in production and development, you should use your own token after signing up at the dahsboard

The quota of the demo token is very limited and is renewed periodically, so please only use it for testing. If you meet any problem to access the above link, please contact us at api@caiyunapp.com

Contact us

Email: api@caiyunapp.com

Business Scenarios

ColorfulClouds Weather API is carefully designed for different scenarios.

Weather apps

Weather apps

The hyperlocal feature:

Global availability:

Drone controlling

Supported languages:

Different unit systems:

Sun rise and set time:

System control & IoT scenarios

In system control scenarios, it is very convenient to set the unit system to SI for calculation, and in many case you only need real-time data, so you can call the API in such a way

Planning scenarios

Web applications

To integrate with a third party data, you need the jsonp support


A global service

Global coverage of minutely forecast

Internationalization

  • the datetime calculation will impact the avg/max/min values of weather variables, our i18n features fully support this.
  • the unit of measurement is fully support i18n requirement, we support Metric system, Imperial and US customary units and International System of Units
  • the user-friendly nature language description of current weather conditions is support i18n, but we only provide Chinese, English and Japanese support.

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.

Data coverage of air quality forecast

Full scope of China.

API Features

Full-scoped variables

You can check a detailed table of the supported variables.

The nowcasting service

We provide two kind of nowcasting service:

  • pointwise API calls specified by latitude and longitude
  • forecasted weather radar images and forecasted data matrix

The AI technology behind

Since the founding at 2014, we always dedicated in improving the algorithms for years, there are many works behind the services.

the 1st generation denoise algorithm
the 3rd generation of precipitation forecast algorithm
the comparison of 1st and 2nd generation air quality forecast

The reliable and stable backend

  • Scalability: the public service pool can offer 300M ~ 800M API calls per day and can be scaled up easily on demanding
  • Availability: the availability of the public service pool for the past year is at 99.94%
the capacity and availability monitoring platform
the technical architecture behind

We can offer private service pool with better availability for large-demanding clients

The team behind

the team members after the annual party
the office and working environment


Appendix 1: table of countries that nowcasting is supported

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


Appendix 2: 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