Batch Requests

One of the most common API requirements is to obtain multiple pieces of information for a location. This can be completed with multiple API requests for each data type, but the /batch request feature provides a more efficient solution. With a batch request, you can query multiple endpoints within a single query without having to learn a new endpoint or request format.

The /batch endpoint uses a requests parameter whose value is a string of comma-separated standard endpoint requests. Each endpoint request must include either an :action or :id along with optional parameters for each request. Each individual request string should be exactly the same as if you were making the request individually, following the same format outlined in each endpoint's documentation.

Additionally, the batch request also supports all of the standard endpoint parameters, such as p, limit, and query, except that when used, these batch parameters are considered global and applied to each individual request provided with the request parameters. Note, however, that any parameters included within an individual request (within the requests parameter) will override those same global options found in the main batch request.

For example:

/batch?limit=10&requests=/observations/closest,/stormreports%3Flimit=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.

Heads Up! Each individual request you include within a single batch call counts as a separate API access against your account's limit. So the above example requesting /observations, /stormreports and /fires would be counted as three API accesses, not one. The /batch endpoint is simply available for convenience.

Use cases

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 but must be URL-encoded, use %3F for ? and %26 for &. 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,/forecasts%3Ffilter=6hr,/advisories%3Ffilter=all

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

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%3Fsort=temp:-1,/observations/search%3Fsort=temp

Here the query=country:us,temp:-999 component 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%3Fsort=-1,/observations/search%3Fsort=temp

Request limits

While the batch request capability is powerful, there is currently a maximum limit of thirty-one (31) endpoint requests per API query. This is normally more than sufficient for most needs, though we will continue to re-evaluate this limit in the future.