GET · /api/v1/navigation/directions

Navigation API

Turn-by-turn directions between two or more points. Returns a GeoJSON route geometry, step-by-step maneuvers with lane guidance, speed limits along the route, and traffic congestion levels. Supports six routing profiles and multi-stop itineraries.

Get Directions

Calculate a route from an origin to a destination, optionally via intermediate stops. Set alternates to receive up to 3 alternative routes alongside the primary one.

GET/navigation/directions

Calculate a route with turn-by-turn instructions

Parameters

NameTypeDescription
originLatnumberLatitude of the starting point (-90 to 90)
originLngnumberLongitude of the starting point (-180 to 180)
destLatnumberLatitude of the destination (-90 to 90)
destLngnumberLongitude of the destination (-180 to 180)
profilestring?Routing profile (default: driving-traffic)
languagestring?Instruction language: fr, ar, or en
alternatesnumber?Number of alternative routes, 0–3 (default: 2)
stopsstring?Comma-separated lat,lng pairs for intermediate stops (e.g. 18.09,-15.97,18.10,-15.98)
skipSpeedLimitsboolean?Skip speed-limit lookup for faster reroute responses
avoidTollsboolean?Avoid toll roads (driving profiles only)
avoidUnpavedboolean?Avoid unpaved roads (driving profiles only)
avoidFerriesboolean?Avoid ferry crossings (driving profiles only)
avoidHighwaysboolean?Avoid highways/motorways (driving profiles only)

Routing Profiles

driving

Car routing without live traffic.

driving-traffic

Car routing with live traffic. Default.

walking

Pedestrian routes along footpaths and sidewalks.

cycling

Bike-friendly routes preferring cycleways.

truck

Heavy-vehicle routing respecting truck restrictions.

motorcycle

Motorcycle routing with two-wheeler rules.

Example Request

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/navigation/directions?\
originLat=18.0858&\
originLng=-15.9785&\
destLat=18.1012&\
destLng=-15.9507&\
profile=driving-traffic&\
language=fr&\
alternates=2&\
avoidTolls=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
JavaScriptjavascript
const params = new URLSearchParams({
  originLat: "18.0858",
  originLng: "-15.9785",
  destLat: "18.1012",
  destLng: "-15.9507",
  profile: "driving-traffic",
  language: "fr",
  alternates: "2",
  avoidTolls: "true",
});

const response = await fetch(
  `https://api.oolelmaps.com/api/v1/navigation/directions?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);

const data = await response.json();
const routes = Array.isArray(data) ? data : [data];

for (const route of routes) {
  console.log(`Distance: ${route.distance}m, duration: ${route.duration}s`);
  for (const step of route.steps) {
    console.log(`${step.instruction} (${step.distance}m, ${step.maneuverType})`);
  }
}
Pythonpython
import requests

response = requests.get(
    "https://api.oolelmaps.com/api/v1/navigation/directions",
    params={
        "originLat": 18.0858,
        "originLng": -15.9785,
        "destLat": 18.1012,
        "destLng": -15.9507,
        "profile": "driving-traffic",
        "language": "fr",
        "alternates": 2,
        "avoidTolls": True,
    },
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

data = response.json()
routes = data if isinstance(data, list) else [data]
for route in routes:
    print(f"{route['distance']}m / {route['duration']}s")

Multi-stop Routes

Pass the stops parameter to insert intermediate waypoints. Format: comma-separated lat,lng pairs (e.g. stops=18.09,-15.97,18.10,-15.98). The route is computed through each stop in order.

cURLbash
curl -X GET "https://api.oolelmaps.com/api/v1/navigation/directions?\
originLat=18.0858&originLng=-15.9785&\
destLat=18.1012&destLng=-15.9507&\
stops=18.0900,-15.9700,18.0950,-15.9600&\
profile=driving" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

[
  {
    "distance": 4379,
    "duration": 338.276,
    "geometry": [
      [-15.946512, 18.092298],
      [-15.948743, 18.089564],
      [-15.950763, 18.091077],
      [-15.951654, 18.091745]
    ],
    "steps": [
      {
        "instruction": "Drive southwest.",
        "distance": 385,
        "duration": 46.218,
        "maneuverType": "start_right",
        "maneuverDirection": "right",
        "maneuverLocation": [-15.946512, 18.092298],
        "name": ""
      },
      {
        "instruction": "Turn right.",
        "distance": 966,
        "duration": 89.419,
        "maneuverType": "right",
        "maneuverDirection": "right",
        "maneuverLocation": [-15.948743, 18.089564],
        "name": ""
      },
      {
        "instruction": "Turn left onto RN1.",
        "distance": 2730,
        "duration": 159.974,
        "maneuverType": "left",
        "maneuverDirection": "left",
        "maneuverLocation": [-15.955915, 18.09493],
        "name": "RN1"
      }
    ],
    "summary": "RN1 → Avenue du Général de Gaulle",
    "maxSpeeds": [
      { "speed": 50 },
      { "speed": 70 }
    ],
    "congestionLevels": [
      "low",
      "moderate",
      "heavy"
    ],
    "pavedRatio": 1
  }
]

Usage Notes

Geometry Format

Route geometry is a GeoJSON LineString with coordinates in [longitude, latitude] order, ready to render directly on MapLibre GL, Leaflet, or any GeoJSON-compatible map library.

Step Fields

Each step includes a maneuverType (depart, turn, continue, merge, roundabout, fork, arrive) and a maneuverDirection (left, right, straight, slight left/right, sharp left/right, uturn) you can map to your own maneuver icons. Lane guidance, when available, is in the step's lanes array.

Alternative Routes

Set alternates to an integer from 0 to 3. When the response contains more than one route, it is returned as a JSON array sorted fastest-first. A single route is returned as a plain object.

Avoidance Flags

avoidTolls, avoidUnpaved, avoidFerries, and avoidHighways apply to the driving and driving-traffic profiles only. They are ignored for walking, cycling, truck, and motorcycle.

Speed Limits & Congestion

When available, the response includes a maxSpeeds array with the posted speed limit along each segment of the geometry, and a congestionLevels array with per-segment traffic levels (low, moderate, heavy, severe).