Source: https://developers.woosmap.com/api-reference/distance-api/get-distance-route-json/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Find Routes # 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`](#authorization-distance-publicapikey) apiKeyquery Public key of the project usually starts with `woos-` [`private_key`](#authorization-distance-privateapikey) apiKeyquery Private key with or without write permission. [`X-Api-Key`](#authorization-distance-privateapikeyheader) apiKeyheader Private key with or without write permission. ### Query Parameters [`waypoints`](#query-waypoints) object 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`](#query-mode) stringDefaults to `driving` Specifies the mode of transport to use for the calculation. Available options:`driving`, `walking`, `cycling` [`method`](#query-method) stringDefaults 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`](#query-units) stringDefaults to `metric` Specifies the unit system to use when displaying results. Available options:`metric`, `imperial` [`language`](#query-language) stringDefaults 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 20 enum values Hide 20 enum values `en` `fr` `ca` `da` `de` `es` `et` `fi` `he` `it` `ja` `nb` `nl` `pl` `pt` `ro` `ru` `sv` `uk` `zh` [`avoid`](#query-avoid) object 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`](#query-arrival-time) object 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`](#query-departure-time) object 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` [`origin`](#query-origin) stringrequired 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`](#query-destination) stringrequired 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` [`alternatives`](#query-alternatives) booleanDefaults 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`](#query-details) stringDefaults to `none` Specifies if maneuver instructions should be returned (roadbook) Available options:`full`, `none` ### Header Parameters [`accept-language`](#header-accept-language) object ### Response 200application/json Successful Response [`status`](#resp-200-status) stringDefaults 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](https://developers.woosmap.com/products/distance-api/distance-matrix-endpoint/#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`](#resp-200-routes) object[]required Contains an array of route options if `alternatives=true` else a single route. #Show 6 propertiesHide 6 properties routes.[`overview_polyline`](#resp-200-routes-overview-polyline) objectrequired The polyline of the route (encoded with the [poyline algorithm](https://developers.google.com/maps/documentation/utilities/polylinealgorithm)). Show 1 propertiesHide 1 properties routes.overview\_polyline.[`points`](#resp-200-routes-overview-polyline-points) stringrequired routes.[`bounds`](#resp-200-routes-bounds) objectrequired A rectangle in geographical coordinates from points at the southwest and northeast corners. Show 2 propertiesHide 2 properties routes.bounds.[`northeast`](#resp-200-routes-bounds-northeast) objectrequired Show 2 propertiesHide 2 properties routes.bounds.northeast.[`lat`](#resp-200-routes-bounds-northeast-lat) numberrequired The latitude of the point in decimal degrees, range is [-90, 90]. routes.bounds.northeast.[`lng`](#resp-200-routes-bounds-northeast-lng) numberrequired The longitude of the point in decimal degrees, range is [-180, 180]. routes.bounds.[`southwest`](#resp-200-routes-bounds-southwest) objectrequired Show 2 propertiesHide 2 properties routes.bounds.southwest.[`lat`](#resp-200-routes-bounds-southwest-lat) numberrequired The latitude of the point in decimal degrees, range is [-90, 90]. routes.bounds.southwest.[`lng`](#resp-200-routes-bounds-southwest-lng) numberrequired The longitude of the point in decimal degrees, range is [-180, 180]. routes.[`notice`](#resp-200-routes-notice) stringrequired Some noticeable information about the route. routes.[`legs`](#resp-200-routes-legs) object[]required Contains an array of sections of the route. Show 10 propertiesHide 10 properties routes.legs.[`distance`](#resp-200-routes-legs-distance) objectrequired 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`](#resp-200-routes-legs-distance-value) integerrequired routes.legs.distance.[`text`](#resp-200-routes-legs-distance-text) stringrequired routes.legs.[`duration`](#resp-200-routes-legs-duration) objectrequired 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`](#resp-200-routes-legs-duration-value) integerrequired routes.legs.duration.[`text`](#resp-200-routes-legs-duration-text) stringrequired routes.legs.[`duration_without_traffic`](#resp-200-routes-legs-duration-without-traffic) RouteDistanceDuration routes.legs.[`start_location`](#resp-200-routes-legs-start-location) objectrequired The starting location of this leg. Show 2 propertiesHide 2 properties routes.legs.start\_location.[`lat`](#resp-200-routes-legs-start-location-lat) numberrequired The latitude of the point in decimal degrees, range is [-90, 90]. routes.legs.start\_location.[`lng`](#resp-200-routes-legs-start-location-lng) numberrequired The longitude of the point in decimal degrees, range is [-180, 180]. routes.legs.[`end_location`](#resp-200-routes-legs-end-location) objectrequired The ending location of this leg. Show 2 propertiesHide 2 properties routes.legs.end\_location.[`lat`](#resp-200-routes-legs-end-location-lat) numberrequired The latitude of the point in decimal degrees, range is [-90, 90]. routes.legs.end\_location.[`lng`](#resp-200-routes-legs-end-location-lng) numberrequired The longitude of the point in decimal degrees, range is [-180, 180]. routes.legs.[`start_waypoint`](#resp-200-routes-legs-start-waypoint) integer The index of the waypoint that is the starting point of this leg. routes.legs.[`end_waypoint`](#resp-200-routes-legs-end-waypoint) integer The index of the waypoint that is the ending point of this leg. routes.legs.[`start_address`](#resp-200-routes-legs-start-address) string The address of the starting point of this leg. routes.legs.[`end_address`](#resp-200-routes-legs-end-address) string The address of the ending point of this leg. routes.legs.[`steps`](#resp-200-routes-legs-steps) array 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. routes.[`main_route_name`](#resp-200-routes-main-route-name) string The main route name based on the longest step length to differentiate routes when alternates are returned. routes.[`recommended`](#resp-200-routes-recommended) boolean Only present and set to true when the route is the recommended route. ### Errors #401 Unable to locate credentials. `application/json` [`detail`](#err-401-detail) stringrequired #402 Out of free quota. `application/json` [`detail`](#err-402-detail) stringrequired #403 Credentials found, but not matching. `application/json` [`detail`](#err-403-detail) stringrequired #422 Validation Error `application/json` [`detail`](#err-422-detail) object[] Show 3 propertiesHide 3 properties detail.[`loc`](#err-422-detail-loc) any[]required detail.[`msg`](#err-422-detail-msg) stringrequired detail.[`type`](#err-422-detail-type) stringrequired #429 Rate limit reached `application/json` [`details`](#err-429-details) stringrequired ```shell 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' ``` ```javascript 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)); ``` ```python 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) ``` ```json { "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 } ] } ```