Responses, Headers, & Errors
Responses
Most successful responses from any endpoint action of the Xweather Phrases API will be in the following form, where the response object will be the text summary string:
{
"response": "...results..."
}However, when making a request using the query parameter stream=true, the result will be generated and returned in real-time.
"...result generated in real-time..."For example, requesting the latest conditions for a known location:
/impacts/general/seattle, wawould return a single string in the response property:
{
"response": "In Seattle, WA, outdoor activities may be impacted by moderate air quality, with an AQI of 54 due to pm2.5 pollution. While the air quality risk is categorized as minimal, individuals sensitive to air pollution should take precautions. Overall, outdoor activities can proceed with caution, ensuring that those particularly affected by air quality remain aware of their limits."
}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 | conditions |
| X-Cost-Tokens | Final cost of the request | 50 |
| X-Cost-Multipliers | How the X-Cost-Tokens were derived. | endpoint=50; 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-product 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.
Please refer to the Phrases API endpoints documentation for the specific access multipliers.
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. |
| 403 | The client id and / or secret are understood but do not have proper access. |
| 404 | The path requested was not found. Verify the endpoint name in your query. |
| 422 | The query parameter was set to an invalid value. |
| 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. |
Please note that the Phrases API does not return these codes inside the response itself, but they are returned via the response status code.
If an error occurs, such as invalid use of a parameter, then the response will entail a single detail property that will contain helpful information for correcting the issue.
A response that contains an error will be similar to the following:
{
"detail":"Invalid location. If providing a city name, include the two letter country code. For example: 'Chicago, US'"
}Or
{
"detail":"Credentials weren't supplied. Pass both headers X-Client-Id & X-Client-Secret or both query params client_id & client_secret with your credentials."
}