Distance Route
How to compute travel distance and time for a path between one origin and one destination.
Complete API Specification: Route Endpoint Reference
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
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.
# Client-side
?origin=48.862,2.329&destination=48.803,2.126&key=YOUR_PUBLIC_KEY
# Server-side
?origin=48.862,2.329&destination=48.803,2.126&private_key=YOUR_PRIVATE_KEY
For complete authentication details and security best practices, see API Keys Documentation.
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 to retrieve the coordinates of an address.
key or private_key - Your API authentication key. See 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
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
Complete Parameter Reference
For all available parameters and advanced options see:
- OpenAPI Specification - Complete technical reference
Request Examples
Basic Itinerary
curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=49.180,-0.362&key=YOUR_KEY"
Itinerary with Waypoints
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
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
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 for the possible values.
- routes contains an array of
route, which in turn each contain aoverview_polyline,bounds,legsandsummaryelement.
Check the Ref Documentation to get the full response details.
Routes
Each routes contains the following fields:
overview_polyline: the polyline of the route (encoding with the poyline algorithmbounds: the bounding box of the routenotice: some noticeable information about the route (for example :notice:Has highway segments)legs: information about route between waypoints and steps if thedetailsparameter is set tofull
The notice field does not provide has toll segments information for traffic-aware requests.
Response Examples
{
"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.