Aeris API 1.0.3 Update
Today we released version 1.0.3 of the Aeris Weather API. This release provides support for auto-complete style queries with the new “starts with” functionality as well as several other minor items. Additionally, with this release we added batch requests as a beta feature! Batch requests allow you to query multiple endpoints with a single request to the servers. Review the version history for a complete list of changes.
A common feature seen in many weather applications is the auto-complete style functionality that queries the server as a user is typing in a location name. Now with the new “starts with” query modifier, this can be accomplished easily. All that is needed is to precede the search string in the query with a caret (^) symbol.
An example of a query searching for words starting with “minn”:
/places/search?query=name:^minn&limit=10
The following uses the same above query but limits it to US locations only:
/places/search?query=name:^minn,country:us&limit=10
We have received many praises and requests for the Aeris Weather API, the most common request being the ability to query multiple endpoints all within a single query. Our new batch request feature takes care of this for you without having to learn a new endpoint or request format. Please note that as of 1.0.3 we consider this a beta feature and a max of 5 endpoints can be performed per batch request.
See the batch request documentation for full usage. The following are the primary features:
The batch endpoint uses a requests parameter set to a string of comma-separated standard endpoint requests. Each endpoint request must include either an :action or :id and its own parameters (optional). If the main batch request uses an :id, then this ID will be automatically passed to each endpoint query.
Additionally, any other parameters passed to the batch request are considered global and passed to each individual endpoint requests found in the requests parameter. Note, however, that the parameters included within an individual endpoint request will override those same options found in the global parameters of the batch request. For example:
/batch?limit=10&requests=/observations/closest,/stormreports?limit=5,/fires/closest
In this batch request, the global option “limit=10” is used by the observations and the fires endpoints, but the stormreports endpoint overrides this with it’s own “limit=5”
Use Case 1 - Fetch multiple data types for the same location:
The is the simplest and most common use of a batch request:
/batch/:id?requests=/:endpoint1,/:endpoint2,/:endpoint3
For example, to fetch the latest observation, daily forecast and active advisories for Minneapolis, MN:
/batch/minneapolis,mn?requests=/observations,/forecasts,/advisories
Parameters can be passed to each individual endpoint as well. For example, to obtain the latest observation, the forecast in daily intervals, the forecast in hourly intervals and all active advisories, the batch request would be:
/batch/minneapolis,mn?requests=/observations,/forecasts,/forecast?filter=6hr,/advisories?filter=all
Use Case 2 - Fetch data for multiple locations:
To fetch the latest observations for Atlanta, Minneapolis and Seattle:
/batch?requests=/observations/atlanta,ga,/observations/minneapolis,mn,/observations/seattle,wa
Use Case 3 - Fetch weather extremes:
The following batch request is combined with the power of the query and sort parameters to return the warmest and coldest locations in the US based on their latest observations:
/batch?limit=1&query=country:us,temp:-999&requests=/observations/search?sort=temp:-1,/observations/search?sort=temp
Here the “query=country:us,temp:-999” queries only observations in the US and only includes observations that have a valid temperature (observations that didn’t report a temperature for a particular hour will have -999 as the temperature value, so we would want to eliminate those that didn’t report).
Often during the winter months the warmest location in the US may be in Puerto Rico. So, adjust the query to eliminate locations in Puerto Rico to query only the 50 states:
/batch?limit=1&query=country:us,state:!pr,,temp:-999&requests=/observations/search?sort=-1,/observations/search?sort=temp
Submit a comment