Source: https://developers.woosmap.com/products/indoor-api/features/distance_matrix/

> 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 Matrix



**Most integrations should use a client library.** The [Map JS API](/products/indoor-api/indoor-js-api/reference/) and [mobile SDKs](/products/mobile/get-started/) 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.
You can also use the `X-Api-Key` header for server-side or mobile authentication.

```bash
# Client-side (query parameter)
?origins=43.6066,3.9218&destinations=ref:cafe002&key=YOUR_PUBLIC_KEY

# Server-side (query parameter)
?origins=43.6066,3.9218&destinations=ref:cafe002&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

| 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

```bash
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);
```