Overview
The SITA Weather API is a REST based service which provides current and forecast weather data for locations around the world. The API consumer can query current conditions and either 5-day or 7-day forecast for airports around the world using just the airport IATA\ICAO code. The APIs can return current conditions, forecasted conditions or both.
Features
The API enables you to:
- Request the current weather information for a single location.
- Request the weather forecast information for a single location for either 5 or 7 days duration depending on the request parameter.
- Request to receive a combination of current and forecast for a single location.
- The APIs also include icons for each weather description enabling you to create a graphical display of the weather information and forecasts within your apps.
The refresh period for current conditions is more frequent than that for forecast conditions. Current conditions are updated every 30 minutes while the forecast is updated 4 times per day, at approximately 0:15, 6:15, 12:15, and 18:15 US Eastern Time.
Example of information included: location: "MIA", phrase: "Mostly cloudy", temperature: "83", heatIndex: "84", windChill: "83", relativeHumidity: "48", relativeHumidityUnits: "%", windDirection: "ESE", windSpeed: "13", pressure: "30.03", pressureUnits: "in/Hg", visibility: "10", feelsLikeTemperature: "82", timeStamp: "2020-05-08T19:19:01Z", icon: "06"
Weather Icons
We also make icons available to enable you to create a graphical display of the weather information and forecasts within your apps. Some sample weather Icons shown below. See our Weather Icon List for full list.
Technical Documentation
1 Revision History
| Date | Version | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2 Definitions, Acronyms and Abbreviations
| Term | Definition |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3 Introduction
The SITA Weather API is a REST based service which provides current and forecast weather data for locations around the world.
3.1 Registration and API Signup
To access the APIs you will need an API key. These can be obtained by creating an account on https://www.developer.aero/ and registering your interest for access to the API.
3.2 Authentication
To access the APIs an OAuth access token must be supplied. To obtain an OAuth token a request must be sent to the https://sitaopen.api.aero/weather/oauth/token endpoint using the OAuth2 Client Credential flow, using your API key as the client_id, and your consumer secret as the client_secret.
Once an access token has been obtained, it can be placed in the Authorization HTTP header as a bearer token, for example:
Authorization: Bearer eyJ92dNw9dka...
3.3 SITA Weather API Structure
The scheme, domain and high level path parameters portion of the URL is:
Where weather is the functional domain. The current version is v1. The current qa server is at https://weather-qa.api.aero.
Following the weather domain parameter, and version, the next path parameter defines the service called. As of this version, the following functions are provided:
| Function | Description |
|---|---|
|
|
|
|
|
|
|
|
|
3.4 Security
-
All incoming requests will be REST over HTTPS.
-
Users are authenticated using their OAuth token.
-
Certain response payload elements will be filtered based on permissions associated with their token.
3.5 Rate Limiting
All incoming requests are subject to a rate limiting restriction. The following headers are included in HTTP responses:
| Header | Description |
|---|---|
|
|
The total number of requests allowed in the current time window |
|
|
The number of requests left for the current time window |
|
|
The policy describing how many request per time window are allowed |
|
|
The UTC timestamp at which the current rate limit window resets |
3.6 Error Response
Response fields
| Path | Type | Description |
|---|---|---|
|
|
|
Object that holds the error information |
|
|
|
Array of errors |
|
|
|
Weather API Internal Error Code |
|
|
|
Error Description |
HTTP response
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 119
{
"errors" : {
"error" : [ {
"description" : "Airport not found.",
"code" : 2020
} ]
}
}
4 SITA Weather API Service
4.1 Current Weather
Path parameters
| Parameter | Description |
|---|---|
|
|
The version of this API. |
|
|
The IATA or ICAO code of the location. |
Request headers
| Name | Description |
|---|---|
|
|
The Content-Type of this request. |
|
|
Authorization header that contains the access token. |
Response fields
| Path | Type | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Curl request
$ curl 'https://www.example.com:12345/v1/current/DUB' -i -X GET \
-H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
-H 'Content-Type: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 556
{
"duration" : "1 day",
"temperatureScale" : "C",
"lengthUnit" : "K",
"currentWeather" : {
"location" : "DUB",
"phrase" : "Partly sunny",
"temperature" : "18",
"heatIndex" : "17",
"windChill" : "18",
"relativeHumidity" : "42",
"relativeHumidityUnits" : "%",
"windDirection" : "WSW",
"windSpeed" : "14.48",
"pressure" : "29.92",
"pressureUnits" : "in/Hg",
"visibility" : "16.09",
"feelsLikeTemperature" : "17",
"timeStamp" : "2018-08-09T13:49:03Z",
"icon" : "03"
}
}
4.2 Forecast Weather
Path parameters
| Parameter | Description |
|---|---|
|
|
The version of this API. |
|
|
The IATA or ICAO code of the location. |
Request headers
| Name | Description |
|---|---|
|
|
The Content-Type of this request. |
|
|
Authorization header that contains the access token. |
Response fields
| Path | Type | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Curl request
$ curl 'https://www.example.com:12345/v1/forecast/DUB' -i -X GET \
-H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
-H 'Content-Type: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1170
{
"duration" : "1 day",
"temperatureScale" : "C",
"lengthUnit" : "K",
"weatherForecast" : [ {
"forecastDate" : "2018-08-09",
"dayName" : "Thursday",
"highTemperatureValue" : "18",
"lowTemperatureValue" : "9",
"feelsLikeHighTemperature" : "17",
"feelsLikeLowTemperature" : "4",
"phrase" : "Partly sunny with a passing shower",
"probabilityOfPrecip" : "55",
"probabilityOfPrecipUnits" : "percent",
"nightPhrase" : "Partly cloudy with a passing shower",
"nightIcon" : "39",
"nightProbabilityOfPrecip" : "55",
"nightProbabilityOfPrecipUnits" : "percent",
"icon" : "14"
}, {
"forecastDate" : "2018-08-10",
"dayName" : "Friday",
"highTemperatureValue" : "18",
"lowTemperatureValue" : "9",
"feelsLikeHighTemperature" : "17",
"feelsLikeLowTemperature" : "9",
"phrase" : "Times of clouds and sun",
"probabilityOfPrecip" : "25",
"probabilityOfPrecipUnits" : "percent",
"nightPhrase" : "Partly cloudy",
"nightIcon" : "35",
"nightProbabilityOfPrecip" : "25",
"nightProbabilityOfPrecipUnits" : "percent",
"icon" : "04"
} ]
}
4.3 Combined Weather
Path parameters
| Parameter | Description |
|---|---|
|
|
The version of this API. |
|
|
The IATA or ICAO code of the location. |
Request headers
| Name | Description |
|---|---|
|
|
The Content-Type of this request. |
|
|
Authorization header that contains the access token. |
Response fields
| Path | Type | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Curl request
$ curl 'https://www.example.com:12345/v1/combined/DUB' -i -X GET \
-H 'Authorization: Bearer eyJkb2N1bWVudGF0aW9uIiwidG9rZW4ifQ...' \
-H 'Content-Type: application/json'
HTTP response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1646
{
"duration" : "1 day",
"temperatureScale" : "C",
"lengthUnit" : "K",
"currentWeather" : {
"location" : "DUB",
"phrase" : "Partly sunny",
"temperature" : "18",
"heatIndex" : "17",
"windChill" : "18",
"relativeHumidity" : "42",
"relativeHumidityUnits" : "%",
"windDirection" : "WSW",
"windSpeed" : "14.48",
"pressure" : "29.92",
"pressureUnits" : "in/Hg",
"visibility" : "16.09",
"feelsLikeTemperature" : "17",
"timeStamp" : "2018-08-09T13:49:03Z",
"icon" : "03"
},
"weatherForecast" : [ {
"forecastDate" : "2018-08-09",
"dayName" : "Thursday",
"highTemperatureValue" : "18",
"lowTemperatureValue" : "9",
"feelsLikeHighTemperature" : "17",
"feelsLikeLowTemperature" : "4",
"phrase" : "Partly sunny with a passing shower",
"probabilityOfPrecip" : "55",
"probabilityOfPrecipUnits" : "percent",
"nightPhrase" : "Partly cloudy with a passing shower",
"nightIcon" : "39",
"nightProbabilityOfPrecip" : "55",
"nightProbabilityOfPrecipUnits" : "percent",
"icon" : "14"
}, {
"forecastDate" : "2018-08-10",
"dayName" : "Friday",
"highTemperatureValue" : "18",
"lowTemperatureValue" : "9",
"feelsLikeHighTemperature" : "17",
"feelsLikeLowTemperature" : "9",
"phrase" : "Times of clouds and sun",
"probabilityOfPrecip" : "25",
"probabilityOfPrecipUnits" : "percent",
"nightPhrase" : "Partly cloudy",
"nightIcon" : "35",
"nightProbabilityOfPrecip" : "25",
"nightProbabilityOfPrecipUnits" : "percent",
"icon" : "04"
} ]
}
Glossary
| Terms | Definitions |
|---|---|
| C | Celsius |
| Current | Reference to requests for the current weather |
| Duration | Parameter for forecast, number of forecasted days |
| F | Fahrenheit |
| Forecast | Reference to requests for the weather forecast |
| K | Kilometers |
| L | Location is an airport, as defined by its IATA code |
| M | Miles |
| W | Weather |
Weather Icon List
The Weather APIs include numbered icons for each weather description. For example, Sunny is Icon 01, represented by a large sun. Below is the table with codes and a URL for corresponding icons.
Contact Us
For subscription and sales queries, please contact:
Product Inquiries
Weather API
Contact Us
For any technical queries and support, please contact:
Technical Support Team
Contact Us
