Route endpoint

How to compute travel distance, time and path for a pair of origin and destination.

  1. Required parameters
  2. Optional parameters
  3. Route endpoint Response
  4. Route endpoint server side
  5. Usage limits
  6. Example

Get distance, duration and path (as a polyline) between an origin and a destination, based on the recommended route between those two points for a specified travel mode. This endpoint provides you all the information needed to evaluate an itinerary and display it on a map. Duration values are provided as complementary info as traffic data are not use to compute the route calculation.

Requests should be build as follows:

https://api.woosmap.com/distance/route/json?parameters

Required parameters

Some parameters are required to initiate a Distance Route API request. As it is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

https://api.woosmap.com/distance/route/json?destination=47.852954,2.290887&origin=49.850077,4.311124&key={PUBLIC_API_KEY}

origin

The starting point for the route. It should be supplied in the form of latitude/longitude coordinates. Ensure that no space exists between the latitude and longitude values.

destination

The ending point for the route. It should be supplied in the form of latitude/longitude coordinates. Ensure that no space exists between the latitude and longitude values.

key

Your project’s API key. This key identifies your Woosmap Project for purposes of quota management. (you should use key client side and private_key server side)

Please refer to the documentation to get an API Key if necessary

Optional parameters

https://api.woosmap.com/distance/route/json?origin=49.850077,4.311124&destination=47.852954,2.290887&mode=driving&language=ru&units=imperial&alternatives=true&details=full&key={PUBLIC_API_KEY}

mode

Specifies the mode of transport to use when calculating distance. Valid values are driving, cycling, walking. (if not specified default is driving)

language

The language code, indicating in which language the results should be returned, if possible. If language is not supplied, the Distance API service will use the navigator language or “en”.

units

Specifies the unit system to use when expressing distance as text. Two different units supported: metric(default) returns distances in kilometers and meters, imperial returns distances in miles and feet.

alternatives

Specifies if alternative routes should be returned. Valid values are true and false (default is false). Depending on the calculated route, alternatives may not be provided.

waypoints

A list of points by which the route should pass (route response is divided into legs, one leg corresponding to a route between two waypoints). Waypoints should be separated by | character.

Optionally, you may pass optimize:true as the first argument within the waypoints parameter. This way the provided route is optimized by rearranging the waypoints in a more efficient order based on distance or time according to the method parameter. The route start point and end point order is not changed, their position is considered fixed.

example : waypoints=optimize:true|48.850077,3.311124|48.850077,3.411124

alternatives and waypoints can not be used at the same time.

method

Specifies the method to compute the route between the start point and the end point:

details

Specifies if maneuver instructions should be returned (roadbook). Valid values are none and full (default is none)

Route endpoint Response

Route provides a JSON response containing the following root elements:
status contains metadata on the request. See Status Codes below.
routes contains an array of route, which in turn each contain a overview_polyline, bounds, legs and summary element.

{
  "status": "OK",
  "routes": [
    {
      "overview_polyline": {
        "points": "polyline_encoding_with_polyline_algorithm"
      },
      "bounds": {
        "northeast": {
          "lat": 49.872968,
          "lng": 4.700457
        },
        "southwest": {
          "lat": 47.843975,
          "lng": 2.288736
        }
      },
      "summary": "Autoroute de l'Est, Autoroute du Soleil",
      "legs": [
        {
          "distance": {
            "text": "264 miles",
            "value": 425459
          },
          "duration": {
            "text": "4 heures 27 minutes",
            "value": 16029
          },
          "start_location": {
            "lat": 49.850077,
            "lng": 4.311124
          },
          "end_location": {
            "lat": 47.852954,
            "lng": 2.290887
          },
          "start_waypoint": 0,
          "end_waypoint": 1,
          "start_address": "D 8043, E 44",
          "end_address": "Chemin de la Tuilerie",
          "steps":[
            {
              "distance": "272 ft",
              "duration": "1 minute",
              "polyline": "_igoHa~hYgApBMHOEKO",
              "start_location": {
                "lat": 49.849924,
                "lng": 4.310893
              },
              "end_location": {
                "lat": 49.850498,
                "lng": 4.310383
              }
              "travel_mode": "DRIVING",
              "instructions":{
                "action": 2,
                "summary": "Conduisez vers le nord-ouest.",
                "verbal_succint": "Conduisez vers le nord-ouest. Ensuite, Tournez à droite.",
                "verbal_before": "Conduisez vers le nord-ouest. Ensuite, Tournez à droite.",
                "verbal_after": "Continuez pendant 80 mètres."
              }
            },
            ...
          ]
        }
      ]
    },
    ...
      ]
    }
  ]
}

Status Codes

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Distance API service (e.g. wrong API Key, wrong/no referer, …).
BACKEND_ERROR indicates a Distance API request could not be processed due to a server error. This may indicate that the origin and/or destination of this pairing could not be matched to the network. The request may or may not succeed if you try again.
MAX_ROUTE_LENGTH_EXCEEDED indicates that the origin and destination are too far away from each other.
OVER_QUERY_LIMIT (associated to a 429 status code) indicates that the number of queries per second (QPS) exceeds the usage limits.

Routes

Each routes contains the following fields:
overview_polyline: the polyline of the route (encoding with the poyline algorithm bounds: the bounding box of the route summary: a short name for the route legs: information about route between waypoints

Legs

Each legs contains the following fields:
distance: the distance of the leg in meters (value) and as text
duration: the duration of the leg in seconds (value) and as text
start_location: the starting location of the leg (it could be different from the given waypoint if there is no road close to it) end_location: the ending location of the leg (it could be different from the given waypoint if there is no road close to it) start_waypoint: the index of the waypoint where the leg starts from (different from the given order in case of reordering) end_waypoint: the index of the waypoint where the leg ends at (different from the given order in case of reordering) start_address: the starting address of the leg
end_address: the ending address of the leg
steps: list of steps constituting the leg. Steps are returned when the details parameter is specified. A step is the most atomic unit of a route, containing a single step describing a specific, single instruction on the journey. The step not only describes the instruction but also contains distance and duration information relating to how this step relates to the following step.

Steps

Each steps contains the following fields:
distance: the distance as text covered by this step until the next step
duration: the typical time as text required to perform the step, until the next step
polyline: the polyline representation of the step (encoding with the poyline algorithm
start_location: the location of the starting point of this step
end_location: the location of the last point of this step
travel_mode: the type of travel mode used
instructions: formatted instructions for this step

Instructions

Each instructions contains the following fields:
action: the action to take for the current step (turn left, merge, straight, etc.). See below for a list.
summary: Written maneuver instruction
verbal_succint: text suitable for use as a verbal alert in a navigation application
verbal_before: text suitable for use as a verbal message immediately prior to the maneuver transition
verbal_after: text suitable for use as a verbal message immediately after the maneuver transition

For action, the allowed values include:
0: none
1: start
2: start right
3: start left
4: destination
5: destination right
6: destination left
7: becomes
8: continue
9: slight right
10: right
11: sharp right
12: uturn right
13: uturn left
14: sharp left
15: left
16: slight left
17: ramp straight
18: ramp right
19: ramp left
20: exit right
21: exit left
22: stay straight
23: stay right
24: stay left
25: merge
26: roundabout enter
27: roundabout exit
28: ferry enter
29: ferry exit
30: transit
31: transit transfer
32: transit remain on
33: transit connection start
34: transit connection transfer
35: transit connection destination
36: post transit connection destination
37: merge right
38: merge left

Route endpoint server side

As for other Woosmap APIs, if you plan to use the Route endpoint of Distance API sever side you must use a private_key in your requests.

.../distance/route/json?origin=48.836,2.237&destination=48.709,2.403&private_key=[Private APIKey]&mode=driving&language=en&units=metrics

Usage limits

The following usage limits are in place for the Route endpoint of Distance API:

Example

Here is a sample of a Distance API call using Javascript. It combines calls to Autocomplete endpoint to get suggestions while typing, a call to Geocode endpoint when clicking a suggestion and a call to Route endpoint using previous call’s result. It queries Route endpoint to get a distance, a duration and a path (as a polyline) of the better route between origin, destination and possible waypoints.

Was this article helpful?
Have more questions? Submit a request