Source: https://developers.woosmap.com/products/distance-api/features/route/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Distance Route **Complete API Specification** : [Route Endpoint Reference](/api-reference/distance-api/get-distance-route-json/) ## What is the Route Endpoint? The Woosmap Route Endpoint is the service dedicated to generating optimized, detailed, single-route itineraries between a defined origin and destination (and optionally, intermediate waypoints). Its main purpose is to provide the precise path required for map visualization and step-by-step directions. ### What It Does The Route Endpoint provides the optimized itinerary between two or more locations. It returns all the specific details needed for navigation and visualization, including the total distance, the estimated travel duration, and the precise path geometry (the actual line to draw on a map). ### Key Characteristics The main goal of this endpoint is to generate all the detailed route data required to accurately visualize the optimized path between two or more positions on a map. ## When to Use This Endpoint The Route Endpoint should be used specifically when your goal is to calculate and visualize a single, detailed itinerary on a map. Here are the key scenarios where the Route Endpoint is the appropriate choice: - **Displaying the Route Path** : When you need the precise geometry (the actual line/polyline) of the recommended route to draw it on an interactive map. - **Turn-by-Turn Directions** : When you need to provide users with a complete, step-by-step roadmap or roadbook for navigation. - **Single-Trip Planning** : When you have a clear origin and destination (and optionally, a few waypoints) and need the most optimized path between them. - **Multi-Stop Itineraries** : When you need a single, optimized route that connects a series of locations in a specific - **As a complement to Matrix** : The perfect complement once an Orgin/Destination pair has been chosen from a larger matrix to get details on the path. Travel time with traffic may require specific product activation. ## API Endpoint ```http GET https://api.woosmap.com/distance/route/json ``` ### Authentication Authenticate using either a `key` (public API key for client-side requests) or `private_key` (for server-side requests). Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code. You can also use the `X-Api-Key` header for server-side or mobile authentication. ```shell # Client-side (query parameter) ?origin=48.862,2.329&destination=48.803,2.126&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?origin=48.862,2.329&destination=48.803,2.126&private_key=YOUR_PRIVATE_KEY # Server-side / Mobile (header) -H "X-Api-Key: YOUR_PRIVATE_KEY" ``` For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/). ## Request Parameters Overview ### Required Parameters **`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. You can use [Localities Geocoding](/products/localities/features/geocoding) to retrieve the coordinates of an address. **`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above. ### Key Optional Parameters **`mode`** - Specifies the mode of transport to use when calculating distance. Valid values are `driving`, `cycling`, `walking`. (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”. [Check Supported Languages](/products/distance-api/concepts/language-support/#language-support-in-route-api) **`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. **`method`** - Specifies the method to compute the route between the start point and the end point: - `time`: fastest route (default) - `distance`: shortest route **`details`** - Specifies if maneuver instructions should be returned (roadbook). Valid values are `none` and `full` (default is `none`) This parameter has no effect if used combined with Traffic awareness parameters. No maneuver instructions are available when requesting traffic awareness. **`avoid` - `waypoints` - `departure-time` - `arrival-time`** - More details in the [Tuning section](/products/distance-api/guides/tuning-route-results/) ## Complete Parameter Reference For all available parameters and advanced options see: - [OpenAPI Specification](/api-reference/distance-api/get-distance-route-json/) - Complete technical reference ## Request Examples ### Basic Itinerary ```shell curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=49.180,-0.362&key=YOUR_KEY" ``` ### Itinerary with Waypoints ```shell curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=49.180,-0.362&waypoints=48.820,1.910|48.667,3.143&key=YOUR_KEY" ``` ### Itinerary with traffic awareness ```shell curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=49.180,-0.362&departure_time=now&key=YOUR_KEY" ``` ### Shortest Itinerary with alternatives ```shell curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=49.180,-0.362&method=distance&alternatives=true&key=YOUR_KEY" ``` ## Understanding the Response Route provides a JSON response containing the following root elements: - **status** contains metadata on the request. Check the [OpenAPI Specification](/api-reference/distance-api/get-distance-route-json/) for the possible values. - **routes** contains an array of `route`, which in turn each contain a `overview_polyline`, `bounds`, `legs` and `summary` element. Check the [Ref Documentation](/api-reference/distance-api/get-distance-route-json/) to get the full response details. #### Routes Each `routes` contains the following fields: - `overview_polyline`: the polyline of the route (encoding with the [poyline algorithm](https://developers.google.com/maps/documentation/utilities/polylinealgorithm) - `bounds`: the bounding box of the route - `notice`: some noticeable information about the route (for example : `notice:Has highway segments`) - `legs`: information about route between waypoints and steps if the `details` parameter is set to `full` The `notice` field does not provide `has toll segments` information for traffic-aware requests. ## Response Examples ```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, }, ], } ``` ## Usage Limits & Quotas The following usage limits are in place for the Distance Route endpoint: - Maximum 25 waypoints per request. - Maximum of 10 queries per second (QPS) per Project (so possibly the sum of client-side and server-side queries) - Max distance between origin and destination should not exceed 500km. ## Working Code Examples Here is a sample call using JavaScript. It queries the Route endpoint to get a distance, a duration and a path (as a polyline) of the better route between origin, destination and possible waypoints. https://demo.woosmap.com/js-samples/samples/directions-advanced/app/dist/ [](https://demo.woosmap.com/js-samples/samples/directions-advanced/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/directions-advanced/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/directions-advanced/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/directions-advanced)