Find Routes

GET

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

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.

Rate limit: 10/1s

Rate limit with TRAFFIC: 20/1s

Authorization

key

apiKey query

Public key of the project usually starts with woos-

private_key

apiKey query

Private key with or without write permission.

X-Api-Key

apiKey header

Private key with or without write permission.

Header Parameters

accept-language

string

Query Parameters

origin

string required

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

Example: 48.709,2.403

destination

string required

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.

Example: 48.768,2.338

waypoints

string

A list of points by which the route should pass (the 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.

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

Example: optimize:true|48.850077,3.311124|48.850077,3.411124

mode

string Defaults to driving

Specifies the mode of transport to use for the calculation.

Available options: driving, walking, cycling

method

string Defaults to time

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

• time: fastest route
• distance: shortest route

Available options: time, distance

units

string Defaults to metric

Specifies the unit system to use when displaying results.

Available options: metric, imperial

language

string Defaults to en

The language code, indicating in the language the response should be in.

If not defined the header Accept-Language of the request will be checked before defaulting to en.

Show 28 enum values Hide 28 enum values

en

fr

bg

ca

cs

da

de

el

es

et

fi

he

hi

hu

it

ja

nb

nl

pl

pt

ro

ru

sk

sl

sv

tr

uk

zh

avoid

string

A list of features that you want to avoid. Valid values are tolls, highways, ferries or polygons coordinates whose vertex latlng are separated by a semicolon ;.

To add multiple features, separate them with the pipe | character.

Example: tolls

arrival_time

string

Specify your desired arrival time.

By using this parameter, Distance will calculate the duration with traffic. Valid values are a UNIX timestamp (e.g. 1600799173 for the date: 22/09/2020 20:26:13) or now.

Use either arrival_time or departure_time, not both.

Example: 1600799173

departure_time

string

Specify your desired departure time.

By using this parameter, Distance will calculate the duration with traffic. Valid values are a UNIX timestamp (e.g. 1600799173 for the date: 22/09/2020 20:26:13) or now.

Use either arrival_time or departure_time, not both.

Example: 1600799173

alternatives

boolean Defaults to false

Specifies if alternative routes should be returned. Depending on the calculated route, alternatives may not be provided. alternatives and waypoints can not be used at the same time.

details

string Defaults to none

Specifies if maneuver instructions should be returned (roadbook)

Available options: full, none

Response

200 application/json

Successful Response

status

string Defaults to OK

The status of the response

• OK: The response contains a valid result.
• INVALID_REQUEST: The request could not be processed.
• MAX_ELEMENTS_EXCEEDED: The product of origins and destinations exceeds the per-query limit (fixed at 200 elts/query).
• MAX_ROUTE_LENGTH_EXCEEDED: One of requested routes is too long and the matrix/route cannot be processed (The limit is 500km).
• REQUEST_DENIED: The API key provided is invalid or does not allow access to this service etc..
• BACKEND_ERROR: The server encountered an unexpected error.
• OVER_QUERY_LIMIT: The request was denied due to the rate limit (see Usage Limits).
• ZERO_RESULTS: No route could be found between the origin and destination.

Show 8 enum values Hide 8 enum values

OK

INVALID_REQUEST

MAX_ELEMENTS_EXCEEDED

MAX_ROUTE_LENGTH_EXCEEDED

REQUEST_DENIED

BACKEND_ERROR

OVER_QUERY_LIMIT

ZERO_RESULTS

routes

object[] required

Contains an array of route options if alternatives=true else a single route.

Show 6 propertiesHide 6 properties

routes. overview_polyline

object required

The polyline of the route (encoded with the poyline algorithm).

Show 1 propertiesHide 1 properties

routes.overview_polyline. points

string required

routes. bounds

object required

A rectangle in geographical coordinates from points at the southwest and northeast corners.

Show 2 propertiesHide 2 properties

routes.bounds. northeast

object required

Show 2 propertiesHide 2 properties

routes.bounds.northeast. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.bounds.northeast. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes.bounds. southwest

object required

Show 2 propertiesHide 2 properties

routes.bounds.southwest. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.bounds.southwest. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes. notice

string required

Some noticeable information about the route.

routes. legs

object[] required

Contains an array of sections of the route.

Show 10 propertiesHide 10 properties

routes.legs. distance

object required

The total distance of this leg expressed in meters (value) and as text. The textual value uses the unit system specified with the units parameter.

Show 2 propertiesHide 2 properties

routes.legs.distance. value

integer required

routes.legs.distance. text

string required

routes.legs. duration

object required

The total duration of this leg expressed in seconds (value) and as text. The textual value uses lang parameter if the langauge is available.

Show 2 propertiesHide 2 properties

routes.legs.duration. value

integer required

routes.legs.duration. text

string required

routes.legs. duration_without_traffic

object | null

Show 2 propertiesHide 2 properties

routes.legs.duration_without_traffic. value

integer required

routes.legs.duration_without_traffic. text

string required

routes.legs. start_location

object required

The starting location of this leg.

Show 2 propertiesHide 2 properties

routes.legs.start_location. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.legs.start_location. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes.legs. end_location

object required

The ending location of this leg.

Show 2 propertiesHide 2 properties

routes.legs.end_location. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.legs.end_location. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes.legs. start_waypoint

integer | null

The index of the waypoint that is the starting point of this leg.

routes.legs. end_waypoint

integer | null

The index of the waypoint that is the ending point of this leg.

routes.legs. start_address

string | null

The address of the starting point of this leg.

routes.legs. end_address

string | null

The address of the ending point of this leg.

routes.legs. steps

object[] | null

List of steps steps for this leg. Steps are returned when details=full. 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.

Show 7 propertiesHide 7 properties

routes.legs.steps. distance

string required

The distance as text covered by this step until the next step.

routes.legs.steps. duration

string required

The typical time as text required until the next step.

routes.legs.steps. polyline

string required

The polyline of the step (encoded with the poyline algorithm).

routes.legs.steps. start_location

object required

The starting location of this step.

Show 2 propertiesHide 2 properties

routes.legs.steps.start_location. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.legs.steps.start_location. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes.legs.steps. end_location

object required

The ending location of this step.

Show 2 propertiesHide 2 properties

routes.legs.steps.end_location. lat

number required

The latitude of the point in decimal degrees, range is [-90, 90].

routes.legs.steps.end_location. lng

number required

The longitude of the point in decimal degrees, range is [-180, 180].

routes.legs.steps. travel_mode

string required

The travel mode of this step.

routes.legs.steps. instructions

object | null

The maneuver instructions for this step.

Show 7 propertiesHide 7 properties

routes.legs.steps.instructions. action

integer | null

The action to take for the current step (turn left, merge, straight, etc.). See list of available actions.

routes.legs.steps.instructions. type

string | null

routes.legs.steps.instructions. summary

string | null

Written maneuver instruction.

routes.legs.steps.instructions. verbal_alert

string | null

The transition alert instruction will prepare the user for the forthcoming transition.

routes.legs.steps.instructions. verbal_succint

string | null

Text suitable for use as a verbal alert in a navigation application.

routes.legs.steps.instructions. verbal_before

string | null

Text suitable for use as a verbal message immediately prior to the maneuver transition.

routes.legs.steps.instructions. verbal_after

string | null

Text suitable for use as a verbal message immediately after the maneuver transition.

routes. main_route_name

string | null

The main route name based on the longest step length to differentiate routes when alternates are returned.

routes. recommended

boolean | null

Only present and set to true when the route is the recommended route.

Errors

401

Unable to locate credentials.

application/json

detail

string required

402

Out of free quota.

application/json

detail

string required

403

Credentials found, but not matching.

application/json

detail

string required

422

Validation Error

application/json

detail

object[]

Show 3 propertiesHide 3 properties

detail. loc

any[] required

detail. msg

string required

detail. type

string required

429

Rate limit reached

application/json

details

string required

cURL

JavaScript

Python

        curl -L 'https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    

        const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    

        import requests

url = "https://api.woosmap.com/distance/route/json?origin=49.31067%2C4.14525&destination=49.31344%2C4.15293&mode=driving&language=en&alternatives=true&method=distance&details=full&key=YOUR_PUBLIC_API_KEY"

payload = {}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)


    

200

        
{
  "status": "OK",
  "routes": [
    {
      "overview_polyline": {
        "points": "a_~kHgrhXu@yAe@y@c@q@e@q@c@o@e@m@y@eAa@g@a@c@Y[UUQQYUQOSOQKSKOKQISIWKSEUEMCQAa@CeA@[E}@EUAOEOGKKIOM[I]Ea@A[?QBIBU?WFWDOLUP[P]j@y@^g@`@i@NUNONMJKJIFELCJBJAHGFIDMBSASBKDILURa@LWt@eAHO"
      },
      "bounds": {
        "northeast": {
          "lat": 49.315678,
          "lng": 4.152915
        },
        "southwest": {
          "lat": 49.31073,
          "lng": 4.145162
        }
      },
      "notice": "",
      "legs": [
        {
          "distance": {
            "text": "1 km",
            "value": 1038
          },
          "duration": {
            "text": "1 min",
            "value": 75
          },
          "start_location": {
            "lat": 49.31067,
            "lng": 4.14525
          },
          "end_location": {
            "lat": 49.31344,
            "lng": 4.15293
          },
          "start_waypoint": 0,
          "end_waypoint": 1,
          "end_address": "D 30",
          "start_address": "D 151",
          "steps": [
            {
              "distance": "676 m",
              "duration": "1 min",
              "polyline": "a_~kHgrhXu@yAe@y@c@q@e@q@c@o@e@m@y@eAa@g@a@c@Y[UUQQYUQOSOQKSKOKQISIWKSEUEMCQAa@CeA@[E}@EUAOEOGKKIOM[I]Ea@A[?Q",
              "start_location": {
                "lat": 49.31073,
                "lng": 4.145163
              },
              "end_location": {
                "lat": 49.315679,
                "lng": 4.149621
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 2,
                "summary": "Drive northeast on D 151.",
                "verbal_succint": "Drive northeast. Then Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_before": "Drive northeast on D 151. Then Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_after": "Continue for 700 meters."
              }
            },
            {
              "distance": "22 m",
              "duration": "1 min",
              "polyline": "}}~kHcniXBIBU?W",
              "start_location": {
                "lat": 49.315679,
                "lng": 4.149621
              },
              "end_location": {
                "lat": 49.31563,
                "lng": 4.149905
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 26,
                "summary": "Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_alert": "Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_succint": "Enter the roundabout and take the 2nd exit.",
                "verbal_before": "Enter the roundabout and take the 2nd exit onto D 30."
              }
            },
            {
              "distance": "198 m",
              "duration": "1 min",
              "polyline": "u}~kH{oiXFWDOLUP[P]j@y@^g@`@i@NUNONMJKJIFELC",
              "start_location": {
                "lat": 49.31563,
                "lng": 4.149905
              },
              "end_location": {
                "lat": 49.314292,
                "lng": 4.151623
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 27,
                "summary": "Exit the roundabout onto D 30.",
                "verbal_succint": "Exit the roundabout.",
                "verbal_before": "Exit the roundabout onto D 30.",
                "verbal_after": "Continue for 200 meters."
              }
            },
            {
              "distance": "46 m",
              "duration": "1 min",
              "polyline": "iu~kHsziXJBJAHGFIDMBSAS",
              "start_location": {
                "lat": 49.314292,
                "lng": 4.151623
              },
              "end_location": {
                "lat": 49.314041,
                "lng": 4.151976
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 26,
                "summary": "Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_alert": "Enter the roundabout and take the 2nd exit onto D 30.",
                "verbal_succint": "Enter the roundabout and take the 2nd exit.",
                "verbal_before": "Enter the roundabout and take the 2nd exit onto D 30."
              }
            },
            {
              "distance": "96 m",
              "duration": "1 min",
              "polyline": "ws~kHy|iXBKDILURa@LWt@eAHO",
              "start_location": {
                "lat": 49.314041,
                "lng": 4.151976
              },
              "end_location": {
                "lat": 49.313431,
                "lng": 4.152916
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 27,
                "summary": "Exit the roundabout onto D 30.",
                "verbal_succint": "Exit the roundabout. Then, in 100 meters, You will arrive at your destination.",
                "verbal_before": "Exit the roundabout onto D 30. Then, in 100 meters, You will arrive at your destination.",
                "verbal_after": "Continue for 100 meters."
              }
            },
            {
              "distance": "1 m",
              "duration": "1 min",
              "polyline": "}o~kHubjX",
              "start_location": {
                "lat": 49.313431,
                "lng": 4.152916
              },
              "end_location": {
                "lat": 49.313431,
                "lng": 4.152916
              },
              "travel_mode": "DRIVING",
              "instructions": {
                "action": 4,
                "summary": "You have arrived at your destination.",
                "verbal_alert": "You will arrive at your destination.",
                "verbal_before": "You have arrived at your destination."
              }
            }
          ]
        }
      ],
      "main_route_name": "D 151",
      "recommended": true
    }
  ]
}

    

Was this helpful?

Failed to send feedback. Please try again.

Thanks for your feedback!