Direction Requests

This endpoint calculates a route or a potential set of alternate routes between 2 or more locations. Locations can either be an address-like representation or a GPS coordinate; the routing service will attempt a best interpretation to render route possibilities.

Examine the available geocode endpoints for more details about address-like representations or GPS coordinate representations.

If two locations are specified in the trajectory and alternates is specified, the service will generate between 1-3 potential routes between the locations. However, if more than two locations are specified in the trajectory, the use of alternates will be ignored and a single route will be returned in the result.

The results of each route will also contain a polyline. This is a set of fine-grained GPS coordinates that can be used to render the precise route when layered on top of a mapping visualization, such as Google Maps.

Lastly, the results of each route will also contain summary information about the total distance that will be traveled, as well as the total estimated time to traverse the route.

Provided along with your desired trajectory, you can supply a speed parameter. To accommodate the widest range of possible transportation modes, this parameter is expected in units of meters. This level of granularity is appropriate for everything from cars to bicycles to aircraft (although - at this time - route generation is constrained to roads).

Beware the use of excessive locations or very long distance routes! Supplying too many trajectory parameters will cause more chance of failure or timeout by the routing service. The exact number is indeterminate and will depend on the inputs you provide; you may need to experiment with your use case to find an ideal maximum.

Similarly, the use of alternate routes can also cause route generation to fail due to excessive calculations or timeouts.

Query Parameters

`point`

A series of locations that represent the desired trajectory of travel. These can be address-like representations or (lat,lng) GPS coordinates. Each specified point should generally be considered a milestone/waypoint in the trajectory, but can also be treated as intermediate waypoints used to massage the result to follow a particular route. For best results, URL-encode this parameter.

(required; at least 2)

`speed`

Expected average speed, in meters/hour. Selected forecast points will use this setting to estimate useful points for retrieving weather results. The forecast points may not precisely match this setting.

This parameter cannot be used if the num_forecast_points parameter is also set.

(optional; default=97000 meters/hour, or approximately 60 miles/hour)

`num_forecast_points`

The exact number of forecast points to return. These will be evenly distributed across the route.

This parameter cannot be used if the speed parameter is also set.

(optional; default=indeterminate)

`alternates`

Whether to generate alternate routes. A maximum of 3 alternate routes will be generated. Be aware that using this option may require significantly more processing time, as well as greater potential routing failure for long routes due to timeouts!

(optional; default=false, alternate routes only calculated when exactly 2 points provided)

`mode`

Desired mode of transit.

Available transit modes:

car - Default routing and weather responses
truck - Routing avoids small roads; weather results are sensitive to high winds
motorcycle - No impact on routing; weather results are sensitive to precipitation
bicycle - No impact on routing; weather results are sensitive to precipitation

(optional; default=car)

`units`

The preferred units of the response.

Available units:

imperial - Imperial units (Fahrenheit and/or miles)
metric - Metric units (Celsius and/or kilometers)

(optional; default=imperial)

Cost

200 points per request

Sample Query

GET https://api.weatherroute.io/v1/routing/directions?point=Chicago,IL,United+States&point=37011&speed=97000&mode=car&alternates=true

Output

This request returns a Directions response object.

The generated route will be returned as a JSON object in a top-level array. If alternate routes are requested in the query parameters, the top-level array may contain more than one full route object.

Sample output

[
  {
    "distance": 722596.188,
    "time": 7.45,
    "polyline": [
      {
        "lat": 41.875563,
        "lng": -87.624336
      },
      ...
    ],
    "forecastPoints": [
      {
        "latitude": 41.875563,
        "longitude": -87.624336,
        "distance": 0.0
      },
      ...
    ]
  },
  ...
]

Join our newsletter to receive the latest Weather Route updates

SERVICES

SERVICES