Route / Directions

The Directions endpoint calculates the optimal route between two indoor locations, providing turn-by-turn navigation instructions, distance, duration, and a polyline for visual display. It supports multi-floor navigation and can apply custom routing profiles.

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

Shell
        # Client-side
?origin=43.6066,3.9218&origin_level=0&destination=ref:cafe002&destination_level=2&key=YOUR_PUBLIC_KEY

# Server-side
?origin=43.6066,3.9218&origin_level=0&destination=ref:cafe002&destination_level=2&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
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

Shell
        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);
});
‹ Details Distance Matrix ›
Was this helpful?