Action: route

BETA 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/longitudes provided via the p query parameter or for longer routes via GeoJSON within a POST request. The route 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.

Heads Up! Each individual 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 when passing directions, many points may be close together and filtering these prior to passing the route to the API will help reduce accesses.

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 allow passing any of the 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.46

An example of the above, but passing a mixture of supported place formats:
/observations/route?p=55415;minnetonka,mn;44.85,-93.46

If your query include any filters, queries or sorting, they will be applied to each location along the route individually. All data will be returned in 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 a 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 parameter object, GeoJSON Points or GeoJSON LineStrings.

A parameter object example:

{
   "p":"44.96,-93.27",
   "id":1,
   "from":"+20minutes"
}
p Location, any 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 LineString or 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:

{
   "geometry":{
      "coordinates":[
         -93.265,
         44.9778
      ],
      "type":"Point"
   },
   "id":"1",
   "properties":{
      "from":"+20minutes"
   }
}

Since a GeoJSON feature may have only one properly 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.

An 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,
  "response": [{
      "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
          }
        }
      },
      "type": "Feature"
    }
  ],
  "success": true
}

Limiting Data Request for Close Points

When making a request for 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 10 miles (16.1 km). This can be adjusted in value by passing the “mindist” parameter. With this parameter you can change the minimum distance between data points to a new value such as “25 miles” or “10km”.