Quickstart: Your First REST API Call

A 5-minute guide to making your first server-side request to the Woosmap Distance REST API using cURL for distance matrix and route.

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 page to create your account and project. Learn more about API Keys and restrictions 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 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 :

        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:

        {
    "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)

        # 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:

        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:

        {
    "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 and Distance Route Features to see all the parameters you can use.
Read the Integration Path Guide project (REST API, JS SDK, Widget, etc.)

‹ Overview Matrix ›