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) for a pair of origin and destination, based on the recommended route between those two points for a specified travel mode. The API returns information consisting of rows containing distance and duration values for each pair of start and end point. 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:

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.,2.290887&origin=49.850077,4.311124&key={PUBLIC_API_KEY}


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.


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.


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,4.311124&destination=47.852954,2.290887&mode=driving&language=ru&units=imperial&alternatives=true&key={PUBLIC_API_KEY}


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


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”.


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.


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.


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.


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

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": 4.31089,
          "lng": 49.84992
        "southwest": {
          "lat": 2.32172,
          "lng": 47.84398
      "summary": "Autoroute de l'Est, Autoroute du Soleil",
      "legs": [
          "distance": {
            "text": "233 miles",
            "value": 374365.6
          "duration": {
            "text": "4 hours 33 mins",
            "value": 16400
          "end_location": {
            "lat": 49.849924,
            "lng": 4.310893
          "start_location": {
            "lat": 47.853489,
            "lng": 2.289723

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.


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.


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)

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:


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