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:

HeaderDescriptionExamples
X-Cost-EndpointEndpoint identifierlightning or conditions/summary
X-Cost-TokensFinal cost of the request30 or 1
X-Cost-MultiplierHow 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 CodeDescription
200The request was handled successfully. Refer to warning table for possible warnings with a 200 code.
401The client id and / or secret passed is not valid. Please verify your credentials.
404The path requested was not found. Verify the endpoint name in your query.
429You have reached your API limit for the time period. This can be your mintely rate limit, or your subscription period limit.
5xxAny 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 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 CodeDescription
deprecatedThe request is using deprecated functionality, or the response has changed.
insufficient_scopeValid OAuth credentials were provided, but the user is not allowed access to the data due to privacy restrictions or account level.
internal_errorAn internal error occurred during the request, but don't worry, our development team has been notified of the error.
invalid_clientEither no OAuth credentials were provided, or the provided client_id and/or client_secret are invalid.
invalid_coordinateThe coordinate or series of coordinates provided with the request are invalid.
invalid_idThe id provided with the request is invalid.
invalid_locationThe location used in the request is invalid or not found in the database.
invalid_queryThe query provided with the request is invalid.
invalid_requestThe requested endpoint or action is invalid and not supported.
maxhits_dailyYou 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_namespaceValid OAuth credentials were provided, the request originated from a domain or application outside of the allowed scope the client was registered with.
maxhits_minMaximum number of accesses per minute reached.
maxhitsMaximum number of accesses reached for subscription period.
invalid_dataThere was a data processing issue with the request you provided.
no_locationA location was not provided.
not_implementedThe requested action is not implemented for this endpoint.

The following warning codes are used within the Aeris API:

Warning CodeDescription
warn_deprecatedThe 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_paramA 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_locationA 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_dataThe request did not return any data.