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. See documentation 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.1 Authentication
To access the APIs an OAuth access token must be supplied in an Authorization header in the request. 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.Use your API key as the client_id, and your consumer secret as the client_secret these should be base64 encoded in an Authorization header when sent to the OAuth endpoint.
Please note the OAuth tokens have an expiry of one hour after the token has been retrieved, after the token has expired you will need to re-issue a request to get a new token.
curl --location 'https://sitaopen.api.aero/weather/oauth/token' \--header 'Authorization: Basic YWJjZGVmZ2hpamtsbW5vcC5xcnN0dXY='
You should then see your OAuth token in the response.
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOJIUzI1NiJ9.eyJyZWZyZXNoX3Rva2VuX2V4cGlyZXNfaW4iOiIzNTk5Iiwic3ViIjoic2l0YSIsImFwaV9cm9kdWN0X2xpc3QiOiJbRE9UUy1GbGlnaHQtQ29ubmVjdGlvbi1JbnRlcm5hbF0iLCJpc3MiOiJ1cm46XC9cL2FwaWdlZS1lZdlLUpXVC1wb2xpY3ktdGVzdCIsImFwaV9hY2Nlc3NfdG9rZW4iOiIweXlIZHduSUdtOGo5WlN6WWtuYTBsWG9ZNTFvIiwiYXBpX3JlZnJlc2hfdG9rZW4iOiJraHNlaXN2T3JwSHBUd2NuUVRHdXdBdVdicXNpamNQTyIsImFwaV9zY29wZSI6IiIsImF1ZCI6ImFwaWdlZS1hcGkiLCJleHAiOj3MzAyOTI3MzIsImFwcF9pZCI6IjIxYzI5NTgyLTIwZTktNDkwMS1hNjExLTVkM2UwM2QxNzFkYiIsImV4cGlyZXNfaW4iOiIzNTk5IiwiaWF0IjoxNzMwMjg5MTMyLCJqdGkiOiI3ZmEzNTU4Mi0xNDhmLTRiMmEtODYxMS0wNWI4NDg5YjFjYmMifQ.g_dFH-08DGADOX9HIk7wzX5edxXejVsnCen27A25TQ0"
Once an access token has been obtained, it can be placed in the Authorization HTTP header as a bearer token, for example:
curl --location 'https://sitaopen.api.aero/weather/v1/combined/MIA' \ --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOJIUzI1NiJ9.eyJyZWZyZXNoX3Rva2VuX2V4cGlyZXNfaW4iOiIzNTk5Iiwic3ViIjoic2l0YSIsImFwaV9cm9kdWN0X2xpc3QiOiJbRE9UUy1GbGlnaHQtQ29ubmVjdGlvbi1JbnRlcm5hbF0iLCJpc3MiOiJ1cm46XC9cL2FwaWdlZS1lZdlLUpXVC1wb2xpY3ktdGVzdCIsImFwaV9hY2Nlc3NfdG9rZW4iOiIweXlIZHduSUdtOGo5WlN6WWtuYTBsWG9ZNTFvIiwiYXBpX3JlZnJlc2hfdG9rZW4iOiJraHNlaXN2T3JwSHBUd2NuUVRHdXdBdVdicXNpamNQTyIsImFwaV9zY29wZSI6IiIsImF1ZCI6ImFwaWdlZS1hcGkiLCJleHAiOj3MzAyOTI3MzIsImFwcF9pZCI6IjIxYzI5NTgyLTIwZTktNDkwMS1hNjExLTVkM2UwM2QxNzFkYiIsImV4cGlyZXNfaW4iOiIzNTk5IiwiaWF0IjoxNzMwMjg5MTMyLCJqdGkiOiI3ZmEzNTU4Mi0xNDhmLTRiMmEtODYxMS0wNWI4NDg5YjFjYmMifQ.g_dFH-08DGADOX9HIk7wzX5edxXejVsnCen27A25TQ0'
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
This section describes each WEATHER API service. Detailed API structure, example requests and responses, JSON schema for request (where appropriate) and responses, and error response codes and formats are included.
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 |
|---|---|---|
|
| Feels like temperature |
|
| Current heat index |
|
| Icon for current weather |
|
| Location of weather |
|
| Phrase for current weather |
|
| Current pressure |
|
| Current pressure units |
|
| Current relative humidity |
|
| Current relative humidity in units |
|
| Temperature |
|
| Timestamp for weather forecast |
|
| Current visibility |
|
| Current wind chill |
|
| Current wind direction |
|
| Current wind speed |
|
| Duration |
|
| Length unit |
|
| Temperature scale |
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 |
|---|---|---|
|
| Duration |
|
| Length unit |
|
| Temperature scale |
|
| Day of week |
|
| High temperature feels like |
|
| Low temperature feels like |
|
| Date of forecast |
|
| High temperature value |
|
| Icon in use for forecast |
|
| Low tempearture value |
|
| Icon in use for overnight forecast |
|
| Overnight weather forecast phrase |
|
| Probability of precipitation overnight |
|
| Probability of precipitation overnight in units |
|
| Weather forecast phrase |
|
| Probability of precipitation |
|
| Probability of precipitation overnight in units |
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 |
|---|---|---|
|
| Feels like temperature |
|
| Current heat index |
|
| Icon for current weather |
|
| Location of weather |
|
| Phrase for current weather |
|
| Current pressure |
|
| Current pressure units |
|
| Current relative humidity |
|
| Current relative humidity in units |
|
| Temperature |
|
| Timestamp for weather forecast |
|
| Current visibility |
|
| Current wind chill |
|
| Current wind direction |
|
| Current wind speed |
|
| Duration |
|
| Length unit |
|
| Temperature scale |
|
| Day of week |
|
| High temperature feels like |
|
| Low temperature feels like |
|
| Date of forecast |
|
| High temperature value |
|
| Icon in use for forecast |
|
| Low tempearture value |
|
| Icon in use for overnight forecast |
|
| Overnight weather forecast phrase |
|
| Probability of precipitation overnight |
|
| Probability of precipitation overnight in units |
|
| Weather forecast phrase |
|
| Probability of precipitation |
|
| Probability of precipitation overnight in units |
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
