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:

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:

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

The following warning codes are used within the Aeris API: