Responses
Most successful responses from any endpoint action of the Aeris Weather API will be in the following form, where the response object will be an array of results as objects:
{
"success": true,
"error": null,
"response": [
...results…
]
}
However, when requesting a result by id using the :id action, you are only expecting a single result to be returned. In this case, the response property will normally* be an object instead of an array:
{
"success": true,
"error": null,
"response": {
...result…
}
}
* The forecast endpoint is an exception, as it will always return an array of result objects.
For example, requesting the latest observations for a known location (an id request) would return a single object in the response:
Request
/observations/seattle,wa
Response
{
"success": true,
"error": null,
"response": {
"id": "KBFI",
"loc": {
"long": -122.31666666667,
"lat": 47.55
},
"place": {
"name": "seattle/boeing",
"state": "wa",
"country": "us"
},
"obTimestamp": 1326552780,
"obDateTime": "2012-01-14T06:53:00-08:00",
"ob": {
"tempC": 3,
....
},
"raw": "KBFI 141453Z 14010KT 8SM -RA OVC018 03/01 A2995",
"relativeTo": {
"lat": 47.60621,
...
}
}
}
To use JSONP, add callback=XXXX to your request and we will return the response as XXXX(...response…).
Errors & Warnings
The error property will always be null if the request was successful, results were returned and there were no errors or warnings.
If there was an error, including no results found, then the error property will be an object containing the error code and a short description of the error. Additionally, the response property will always be an empty array. It is recommended for applications to display appropriate error messages when an error occurs based on the error codes described below.
If a warning is issued, such as invalid use of a parameter, then the error property will be an object containing the warning code and a short description of the warning. With a warning, the API will continue, so the request will be successful and results will be returned.
A response that contains an error will be similar to the following:
{
"success": false,
"error": {
"code": "invalid_location",
"description": "The requested location was not found in the database."
},
"response": [ ]
}
The following error codes are used within the Aeris API.
| Error Code | Description |
|---|---|
| invalid_client | Either no OAuth credentials were provided, or the provided client_id and/or client_secret are invalid. |
| insufficient_scope | Valid OAuth credentials were provided, but the user is not allowed access to the data due to privacy restrictions or account level. |
| unauthorized_namespace | Valid OAuth credentials were provided, the request originated from a domain or application outside of the allowed scope the client was registered with. |
| invalid_request | The requested endpoint or action is invalid and not supported. |
| invalid_location | The location used in the request is invalid or not found in the database. |
| invalid_id | The id provided with the request is invalid. |
| invalid_coordinate | The coordinate or series of coordinates provided with the request are invalid. |
| invalid_query | The query provided with the request is invalid. |
| deprecated | The request is using deprecated functionality, or the response has changed. |
| internal_error | An internal error occurred during the request, but don’t worry, our development team has been notified of the error. |
The following warning codes are used within the Aeris API.
| Warning Code | Description |
|---|---|
| warn_no_data | The request did not return any data. |
| warn_invalid_param | The provided parameter was used improperly. |
| warn_deprecated | The request is using deprecated functionality or the response has changed. The API was able to handle the request without errors, so only a warning was issued. |
| warn_maxhits_daily | You have reached your maximum daily access limit for your account. Your account will not be affected immediately when this warning occurs as we provide a certain percentage overage before disabling your service. |