Responses, Headers, & Errors
Responses
Most successful responses from any endpoint action of the Xweather 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...
}
}
For example, requesting the latest observations for a known location (an :id
request):
/observations/seattle,wa
would return a single object in the response
property:
{
"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,
...
}
}
}
Response Headers
The API will include the cost of each request in the response. This allows clients to track the cost associated with each request, and the multipliers being used for the request.
The following response headers are available in each response:
Header | Description | Examples |
---|---|---|
X-Cost-Endpoint | Endpoint identifier | lightning or conditions/summary |
X-Cost-Tokens | Final cost of the request | 30 or 1 |
X-Cost-Multiplier | How the X-Cost-Tokens were dervied. | endpoint=10; spatial=3; temporal=1 or endpoint=1; spatial=1; temporal=1 |
Overall usage is determined by three factors which can be multiplied to find the X-Cost-Tokens
value.
- Endpoint: A sub-prodoct of the API, they are comprised of one of more data sets of varying value.
- Spatial: The geographical area that was queried. Larger areas will generate a higher spatial multiplier.
- Temporal: The time range of the data returned will determine this value.
In addition to cost based headers, refer to the Rate Limiting documentation (opens in a new tab) for headers related to rate limits.
Errors & Warnings
The API will use a variety of HTTP status codes when returning a response. These will align with status code standards. Here is the list of possible codes below:
HTTP Status Code | Description |
---|---|
200 | The request was handled successfully. Refer to warning table for possible warnings with a 200 code. |
401 | The client id and / or secret passed is not valid. Please verify your credentials. |
404 | The path requested was not found. Verify the endpoint name in your query. |
429 | You have reached your API limit for the time period. This can be your mintely rate limit, or your subscription period limit. |
5xx | Any 5xx series is likely due to a server error. Our monitoring systems track these errors, but feel free to contact support (opens in a new tab) with your query. |
Within your JSON document, 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, the success
true, meaning 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": [ ]
}
A response that contains a warning will be similar to the following:
{
"success": true,
"error": {
"code": "warn_location",
"description": "No state/province provided, using location based on population."
},
"response": {
"loc" : {
"lat":37.22957,
"long":-80.41394
},
...
}
}
The following error codes are used within the Aeris API:
Error Code | Description |
---|---|
deprecated | The request is using deprecated functionality, or the response has changed. |
insufficient_scope | Valid OAuth credentials were provided, but the user is not allowed access to the data due to privacy restrictions or account level. |
internal_error | An internal error occurred during the request, but don't worry, our development team has been notified of the error. |
invalid_client | Either no OAuth credentials were provided, or the provided client_id and/or client_secret are invalid. |
invalid_coordinate | The coordinate or series of coordinates provided with the request are invalid. |
invalid_id | The id provided with the request is invalid. |
invalid_location | The location used in the request is invalid or not found in the database. |
invalid_query | The query provided with the request is invalid. |
invalid_request | The requested endpoint or action is invalid and not supported. |
maxhits_daily | You have reached your maximum daily access limit for your account. Further API accesses will receive this error, until the daily count resets at 00 UTC (midnight UTC) |
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. |
maxhits_min | Maximum number of accesses per minute reached. |
maxhits | Maximum number of accesses reached for subscription period. |
invalid_data | There was a data processing issue with the request you provided. |
no_location | A location was not provided. |
not_implemented | The requested action is not implemented for this endpoint. |
The following warning codes are used within the Aeris API:
Warning Code | Description |
---|---|
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_invalid_param | A provided parameter was used improperly or your subscription level does not allow access to the parameter and it was removed. If a parameter was removed from the request, the response will return the same data as if that parameter was not used initially with the request. |
warn_location | A complete location was not provided, so the API made some assumptions. Often seen if a state/province is not provided for US or Canadian location. For example: Atlanta,US or Toronto, CA. |
warn_no_data | The request did not return any data. |