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 property:

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, the successtrue, 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.

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.