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

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Route / Directions



**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 Directions Endpoint?

Calculates the optimal path between two indoor locations, providing turn-by-turn instructions, distance, duration, and visual route geometry.

## When to Use This Endpoint

The Directions endpoint is for any scenario that needs a complete path with turn-by-turn instructions — guiding a visitor from the entrance to a specific shop, routing a wheelchair user via lifts and ramps only, directing staff through restricted areas, or orchestrating a multi-stop journey through intermediate waypoints. The response includes a polyline for visual display on the map as well as human-readable instructions and level-change markers for multi-floor transitions.

## API Endpoint

```http
GET https://api.woosmap.com/indoor/directions/{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)
?origin=43.6066,3.9218&origin_level=0&destination=ref:cafe002&destination_level=2&key=YOUR_PUBLIC_KEY

# Server-side (query parameter)
?origin=43.6066,3.9218&origin_level=0&destination=ref:cafe002&destination_level=2&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               |
| `origin`               | string  | Starting point (lat,lng or POI ID) |
| `origin_level`         | integer | Starting floor level               |
| `destination`          | string  | Ending point (lat,lng or POI ID)   |
| `destination_level`    | integer | Ending floor level                 |

### Key Optional Parameters

| Parameter   | Type   | Description                                                |
| ----------- | ------ | ---------------------------------------------------------- |
| `profile`   | string | Routing profile (e.g., "accessible", "staff", "premium")   |
| `language`  | string | Language for instructions (e.g., "en", "fr", "de")         |
| `units`     | string | Distance units: "metric" or "imperial" (default: "metric") |
| `avoid`     | string | Features to avoid (e.g., "stairs", "escalators")           |
| `waypoints` | string | Intermediate stops (pipe-separated lat,lng pairs)          |

### Request Example

```bash
GET https://api.woosmap.com/indoor/directions/gdn_doc?
  origin=43.6066,3.9218&
  origin_level=0&
  destination=ref:bakery001&
  destination_level=1&
  language=en&
  units=metric&
  key=YOUR_API_KEY
```

```javascript
const params = new URLSearchParams({
  origin: "43.6066,3.9218",
  origin_level: 0,
  destination: "ref:bakery001",
  destination_level: 1,
  language: "en",
  units: "metric",
  key: "YOUR_API_KEY",
});

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

## Response Format

The API returns routes containing legs (segments between waypoints). Each leg includes distance, duration, and turn-by-turn steps with instructions, coordinates, and level information. Steps include maneuvers (turn types), polylines for map rendering, and POI landmarks.

### Response Fields

| Field            | Type   | Description                                                   |
| ---------------- | ------ | ------------------------------------------------------------- |
| `routes`         | array  | Array of possible routes                                      |
| `summary`        | string | Route description                                             |
| `legs`           | array  | Route segments (one per waypoint)                             |
| `distance`       | object | Total distance with value and formatted text                  |
| `duration`       | object | Estimated time with value (seconds) and text                  |
| `start_location` | object | Starting coordinates with level                               |
| `end_location`   | object | Ending coordinates with level                                 |
| `steps`          | array  | Turn-by-turn instructions                                     |
| `instruction`    | string | Human-readable navigation instruction                         |
| `maneuver`       | string | Maneuver type (e.g., "turn_left", "straight", "level_change") |
| `polyline`       | array  | Coordinate array for map rendering                            |
| `bounds`         | object | Geographic bounds of the route                                |

### Maneuver Types

- `straight`: Continue straight
- `turn_left`: Turn left
- `turn_right`: Turn right
- `turn_slight_left`: Slight left turn
- `turn_slight_right`: Slight right turn
- `turn_sharp_left`: Sharp left turn
- `turn_sharp_right`: Sharp right turn
- `level_change`: Change floor level
- `uturn`: Make a U-turn

### Status Codes

- `OK`: Route computed successfully
- `NOT_FOUND`: No route found between origin and destination
- `ZERO_RESULTS`: Origin or destination not accessible
- `INVALID_REQUEST`: Missing or invalid parameters
- `REQUEST_DENIED`: Invalid API key or unauthorized access

## Implementation Notes

Always pass `origin_level` and `destination_level` explicitly — omitting them can produce ambiguous results in multi-floor venues. Select the routing `profile` based on the user's context rather than defaulting to the standard profile: a wheelchair user needs `wheelchair` to avoid stairs, while staff may need a profile that includes restricted corridors. When rendering the route via the Map JS API, pass the full result to `indoorRenderer.setDirections()` rather than parsing the polyline manually; the renderer handles floor-switching and visual transitions automatically.

## Usage with Map JS API

```javascript
// Using Indoor Service for directions
const indoorService = new window.woosmap.map.IndoorService();
const indoorRenderer = new woosmap.map.IndoorRenderer({
  venue: "gdn_doc",
});

const directionsRequest = {
  venueId: "gdn_doc",
  origin: new woosmap.map.LatLng(43.6066, 3.9218),
  originLevel: 0,
  destinationId: "ref:bakery001",
  destinationLevel: 1,
  language: "en",
  units: "metric",
};

indoorService.directions(directionsRequest, (result) => {
  indoorRenderer.setDirections(result);
});
```