Distance Matrix

The Distance Matrix endpoint computes travel distances and durations between multiple origins and destinations within your indoor venue. This is ideal for batch calculations, finding the nearest POIs, or optimizing multi-stop routes.

Most integrations should use a client library. The Map JS API and mobile SDKs handle authentication, map binding, and error handling automatically. Call the REST API directly only when building a backend service or a platform where the JS library is unavailable.

What is the Distance Matrix Endpoint?

Computes travel distances and durations between multiple origins and destinations in a single request, enabling efficient batch calculations and proximity-based sorting.

When to Use This Endpoint

The Distance Matrix is for situations where you need to compare distances across multiple locations in one call, rather than computing individual routes. The classic case is finding the nearest POI of a given type — the closest restroom, exit, or help desk from a user’s current position — by sending one origin against several destinations and sorting the results by distance value. It also handles many-to-many calculations for staff dispatching or service-area analysis. The hard limit is 100 total elements (origins × destinations), so for larger batches you’ll need to split the request.

API Endpoint

http
        GET https://api.woosmap.com/indoor/distancematrix/{venueId}/

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.

Shell
        # Client-side
?origins=43.6066,3.9218&destinations=ref:cafe002&key=YOUR_PUBLIC_KEY

# Server-side
?origins=43.6066,3.9218&destinations=ref:cafe002&private_key=YOUR_PRIVATE_KEY

For complete authentication details and security best practices, see API Keys Documentation.

Request Parameters Overview

Required Parameters

Parameter Type Description
key or private_key string Your Woosmap API key
origins string Pipe-separated list of starting points (lat,lng or POI IDs)
destinations string Pipe-separated list of ending points (lat,lng or POI IDs)

Key Optional Parameters

Parameter Type Description
level integer Floor level for calculations (if all points on same level)
profile string Routing profile (e.g., “accessible”, “staff”)
language string Language for formatted text (e.g., “en”, “fr”)
units string Distance units: “metric” or “imperial” (default: “metric”)
mode string Calculation mode: “walking” (default)

Request Example

Shell
        GET https://api.woosmap.com/indoor/distancematrix/gdn_doc?
  origins=43.6066,3.9218|ref:entrance001&
  destinations=ref:bakery001|ref:cafe002|ref:restroom003&
  level=1&
  units=metric&
  key=YOUR_API_KEY
javascript
        const params = new URLSearchParams({
  origins: "43.6066,3.9218|ref:entrance001",
  destinations: "ref:bakery001|ref:cafe002|ref:restroom003",
  level: 1,
  units: "metric",
  key: "YOUR_API_KEY"
});

const response = await fetch(
  `https://api.woosmap.com/indoor/distancematrix/${venueId}?${params}`
);
const matrix = await response.json();

Response Format

The API returns a matrix with rows (one per origin) containing elements (one per destination). Each element includes distance and duration with both raw values and formatted text.

Response Fields

Field Type Description
rows array Results array (one row per origin)
elements array Results array (one element per destination)
distance object Distance with value (meters) and formatted text
duration object Duration with value (seconds) and formatted text
status string Status for this origin-destination pair

Element Status Codes

  • OK: Distance calculated successfully
  • NOT_FOUND: No route found between this origin-destination pair
  • ZERO_RESULTS: Origin or destination not accessible
  • MAX_ROUTE_LENGTH_EXCEEDED: Route too long to calculate

Overall Status Codes

  • OK: Request processed successfully
  • INVALID_REQUEST: Missing or invalid parameters
  • MAX_ELEMENTS_EXCEEDED: Too many origin-destination pairs (limit: 100)
  • REQUEST_DENIED: Invalid API key or unauthorized access
  • OVER_QUERY_LIMIT: Rate limit exceeded

Implementation Notes

Not every element in the response will have status OK — a destination that can’t be reached from a given origin will return NOT_FOUND, so always check element status before comparing distance values. When all points are on the same floor, pass the level parameter to avoid ambiguity in multi-storey venues. For frequently accessed combinations (e.g., the nearest exit from each department), caching the matrix results is straightforward since venue layout rarely changes.

Finding Nearest POI Example

javascript
        // Find nearest restroom from user's location
const params = new URLSearchParams({
  origins: "43.6066,3.9218",  // User location
  destinations: "ref:restroom001|ref:restroom002|ref:restroom003",
  level: 1,
  units: "metric",
  key: "YOUR_API_KEY"
});

const response = await fetch(
  `https://api.woosmap.com/indoor/distancematrix/${venueId}?${params}`
);
const matrix = await response.json();

// Find minimum distance
const elements = matrix.rows[0].elements;
let nearestIndex = 0;
let minDistance = elements[0].distance.value;

elements.forEach((element, index) => {
  if (element.status === "OK" && element.distance.value < minDistance) {
    minDistance = element.distance.value;
    nearestIndex = index;
  }
});

console.log("Nearest restroom:", matrix.destination_addresses[nearestIndex]);
console.log("Distance:", elements[nearestIndex].distance.text);
‹ Route / Directions Get Started ›
Was this helpful?