Source: https://developers.woosmap.com/products/distance-api/tutorials/making-first-request/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Quickstart: Your First REST API Call We'll try to demonstrate how to find the closest point to the user and then route the user to it, using two powerful calls: - Retrieving distances and travel times for multiple locations using Distance Matrix. - Generating the complete, detailed route between your starting position and one chosen destination using Distance Route. **Ready to start?** ## What You Need You'll need a **private API key** for server-side requests. If you're new to Woosmap, start with the [Get Started](/get-started/) page to create your account and project. Learn more about [API Keys and restrictions](/api-reference/authentication/) to understand how to secure them properly. Don't expose your private key in client-side code or commit it to version control. You'll also need [cURL](https://curl.se/) or any HTTP client (Postman, Insomnia, etc.). The examples below use cURL since it's popular and available on most systems. ## Step 1: Get distance and travel time First, get the distances and travel time by car between the starting point `48.865,2.347` and the three locations `48.667,3.143` `48.820,1.910` `49.180,-0.362` : ```bash curl "https://api.woosmap.com/distance/distancematrix/json?origins=48.865,2.347&destinations=48.667,3.143|48.820,1.910|49.180,-0.362&mode=driving&elements=duration_distance&private_key=YOUR_PRIVATE_API_KEY" ``` Replace `YOUR_PRIVATE_API_KEY` with your actual key. ## Step 2: Understand the Response The API returns a JSON object where the key data is nested within a `rows` array. Each object within the `rows` array represents a single origin location. Inside each origin object, the `elements` array provides the distance and time data for every destination paired with that origin. The order of the `rows` array is the order of the origin locations. The order of the `elements` array within each row is the order of the destinations. Here's the response for the example request: ```json { "status": "OK", "rows": [ { "elements": [ { "status": "OK", "distance": { "value": 75618, "text": "75.6 km" }, "duration": { "value": 5546, "text": "1 heure 32 minutes" } }, { "status": "OK", "distance": { "value": 42641, "text": "42.6 km" }, "duration": { "value": 2802, "text": "47 minutes" } }, { "status": "OK", "distance": { "value": 235318, "text": "235 km" }, "duration": { "value": 9365, "text": "2 heures 36 minutes" } } ] } ] } ``` ## Step 3: Choose the best destination (shortest) From the matrix response above, we need to pick the destination with the smallest `distance.value` from our origin. - We prefer the shortest distance by default (your request), but you could choose the smallest `duration.value` instead - Skip any element whose `status` is not `OK` (e.g., `ZERO_RESULTS`). Pseudocode ``` let destinations = [ "48.667,3.143", "48.820,1.910", "49.180,-0.362" ] let elements = response.rows[0].elements let valid = filter elements where element.status == "OK" let best = min(valid, by = element.distance.value) let best_index = indexOf(elements, best) let best_destination = destinations[best_index] ``` Using jq (shell) ```bash # Save the JSON above to matrix.json, then run: best_index=$(jq -r '.rows[0].elements | to_entries | map(select(.value.status=="OK")) | sort_by(.value.distance.value) | .[0].key' matrix.json) # With our inputs, index 0 corresponds to 48.820,1.910 ``` In our example, the shortest destination is 48.820,1.910 ## Step 4: Get the detailed path to the chosen destination Use the Route Endpoint to get the full path between the origin and the destination you selected in Step 3: ```bash curl "https://api.woosmap.com/distance/route/json?origin=48.865,2.347&destination=48.820,1.910&mode=driving&elements=duration_distance&private_key=YOUR_PRIVATE_API_KEY" ``` Now you get everything to draw the route on a map: ```json { "status": "OK", "routes": [ { "overview_polyline": { "points": "w{fiHmjiMAtFDj@?@AFId@Mv@...." }, "bounds": { "northeast": { "lat": 48.892326, "lng": 2.34679 }, "southwest": { "lat": 48.796319, "lng": 1.903444 } }, "notice": "Has highway segments", "legs": [ { "distance": { "value": 43243, "text": "43.2 km" }, "duration": { "value": 2754, "text": "46 minutes" }, "start_location": { "lat": 48.865, "lng": 2.347 }, "end_location": { "lat": 48.82, "lng": 1.91 }, "start_waypoint": 0, "end_waypoint": 1 } ], "main_route_name": "A 13" } ] } ``` The response gives you details about the route: - `overview_polyline` - Contains the polyline of the route, allowing you to display it on a map - `bounds` - The bounding box of the route, to centre the map on - `notice` - Provide some information or restrictions about the route - `legs` - The calculated distance and travel time from the origin to the final destination, including any intermediate segments defined by waypoints - `main_route_name` - The label of the longest road in the itinerary ## What's Next - Check out [Distance Matrix Features](/products/distance-api/features/matrix/) and [Distance Route Features](/products/distance-api/features/route/) to see all the parameters you can use. - Read the [Integration Path Guide](/products/distance-api/guides/integration-path/) project (REST API, JS SDK, Widget, etc.)