Route endpoint

How to compute travel distance, time and path for a pair of origin and destination.
  1. Required parameters
    1. origin
    2. destination
    3. key
  2. Optional parameters
    1. mode
    2. language
    3. units
    4. alternatives
    5. waypoints
  3. Route endpoint Response
    1. Status Codes
    2. Routes
      1. Legs
  4. Route endpoint server side
  5. Usage limits

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 follow:

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?parameters?destination=47.852954,2.290887&origin=49.850077,4.311124&key=woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx

origin

The starting point for the route. It should be supply 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 supply 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?parameters?origin=49.850077,4.311124&destination=47.852954,2.290887&mode=driving&language=ru&units=imperial&alternatives=true&key=woos-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx

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 of 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. (example : waypoints=48.850077,3.311124|48.850077,3.411124)

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

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.0
          },
          "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, …).
UNKNOWN_ERROR indicates a Distance API request could not be processed due to a server error. The request may succeed if you try again.
NOT_FOUND indicates that the origin and/or destination of this pairing could not be matched to the network.
ZERO_RESULTS indicates no route could be found between the origin and destination. 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)

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:

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