route
The route action returns data for points along a given route. This can be useful to obtain weather information along a transportation route, trails and more. The route is a series of locations, usually latitude/longitude coordinates provided via the p query parameter or for longer routes via GeoJSON within a POST request.
The route action will return an array of GeoJSON points with the requested data for each point.
Defining a Route
A route is a string of points that information is required for. A route should have a minimum of two points and a maximum in the tens, hundreds, or thousands, with your API level being the core limiting factor.
Note: The route action does not generate routing directions between points but is utilized to obtain the weather along a supplied route. Actual routing directions can be obtained from third-party services such as the MapBox Directions API (opens in a new tab), which can be passed to the weather API via the route action.
Heads Up! Each point within the route counts as a separate API access against your account’s daily limit. Passing a route with 500 points will count as 500 API accesses. Often, many points may be close together when passing directions, and filtering these before passing the route to the API will help reduce access.
A route can be supplied to the API via two methods: using a query string for short routes or a POST request for longer routes.
Routes via Query String
For routes, there are just a few points. Passing via query string may be the simplest method. The locations along the route can be passed within the p parameter, separating each point with a semicolon. Normally, a point will be a latitude, longitude combination, though the API will pass any Supported Place formats.
An example query to fetch observations along a route of three points:
/observations/route?p=44.96,-93.27;44.91,-93.5;44.85,-93.46An example of the above, but passing a mixture of supported place formats:
/observations/route?p=44.96,-93.27;44.91,-93.5;44.85,-93.46If your query includes any filters, queries, or sorting, they will be applied to each location along the route individually. All data will be returned in an array of GeoJSON objects in the order of the supplied points.
Routes via POST / JSON
For larger routes, the query string option may not be sufficient. For these queries, you may perform an HTTP post, passing a JSON object within the body of the post. This option is also recommended if you need to pass the time for data a point. For instance, if you have an estimated time at each point along the route, the API can provide forecast data for that time period.
The JSON object should be an array of objects. The objects can include the parameter object, GeoJSON Points or GeoJSON LineStrings.
A parameter object example:
{
"p":"44.96,-93.27",
"id":1,
"from":"+20minutes"
}-
p: Location inany supported place format
-
id: (optional) If provided, the returned GeoJSON object will use this ID
-
from: (optional) If provided, will set the time period for the data request
Additionally, one or more GeoJSON Features that contains a LineString or a Point objects may be provided. When passing a GeoJSON object, if additional parameters are to be included, such as 'from,' these should be included in the properties object of the GeoJSON feature. For Example:
[
{
"type": "Feature",
"geometry": {
"coordinates": [
-93.265,
44.9778
],
"type": "Point"
},
"id": "1",
"properties": {
"from": "+20minutes"
}
}
]Since a GeoJSON feature may have only one property object, if you have a LineString and need to pass parameters (from) for each point, you should convert the LineString to a series of individual GeoJSON Point objects. This will allow each point to have its own property object and associated parameters.
Route Action Output
The route action will provide output as an array of GeoJSON point features. The properties object will contain information on the original request and the requested weather data.
A sample query fetching the current temperature for three cities along a route may look similar too:
/observations/route?p=55415;55403;55344&fields=request,ob.tempF
{
"error": null,
"success": true,
"response": [
{
"type": "Feature",
"geometry": {
"coordinates": [
-93.265,
44.9778
],
"type": "Point"
},
"id": "55415",
"properties": {
"request": {
"error": null,
"id": "55415",
"skipped": false,
"success": true
},
"response": {
"ob": {
"tempF": 16
}
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-93.265,
44.9778
],
"type": "Point"
},
"id": "55403",
"properties": {
"request": {
"error": null,
"id": "55403",
"skipped": true,
"success": true
}
}
},
{
"type": "Feature",
"geometry": {
"coordinates": [
-93.47079,
44.85469
],
"type": "Point"
},
"id": "55344",
"properties": {
"request": {
"error": null,
"id": "55344",
"skipped": false,
"success": true
},
"response": {
"ob": {
"tempF": 18
}
}
}
}
]
}Limiting Data Request for Close Points
When requesting data, often, many route points may be very close together. To help improve the efficiency of the API and limit duplicate data, the API will only fetch data for points with a minimum distance along the route.
The default minimum distance is one kilometer. This can be adjusted in value by using the mindist parameter. You can change the minimum distance between data points to a new value such as “25 miles” or “10km” with this parameter.
The minimum value allowed for the mindist parameter is 1 meter ("1m" or "1meter")