Route

Executive Summary

The Route endpoint computes a navigable path between two coordinates and returns the total travel distance, estimated travel time, and step-by-step navigation instructions.

Use it for:

Navigation UIs
ETA calculation
Map previews
Route planning

Base URL

text

https://api.dev.ambalaymaps.com

Endpoint

Method: POST
Path: /services/route
Allowed Service: ROUTING
Billed Service: ROUTING

Authentication

Route requests require a valid API key in the request header.

http

POST /services/route HTTP/1.1
Host: api.dev.ambalaymaps.com
Content-Type: application/json
x-ambalay-key: {API_KEY}

Purpose

Compute a route from one point to another, optionally through intermediate waypoints, and return distance, duration, and turn-by-turn instructions.

Request Body

Field	Type	Required	Description
`source`	object	Yes	Starting coordinate
`destination`	object	Yes	Destination coordinate
`via`	`array<object>`	No	Ordered intermediate waypoints to route through
`costing`	string	Yes	Travel mode

Coordinate Object

Field	Type	Required	Description
`lat`	number	Yes	Latitude
`lon`	number	Yes	Longitude

Allowed Costing Values

AUTO
PEDESTRIAN
BICYCLE
TRUCK

Rules

source and destination are required
via is optional and supports up to 10 waypoints
All coordinates must be valid numeric latitude/longitude values
costing must be one of:
- AUTO
- PEDESTRIAN
- BICYCLE
- TRUCK

Request Schema

json

{
"type": "object",
"properties": {
  "source": {
    "type": "object",
    "properties": {
      "lat": { "type": "number" },
      "lon": { "type": "number" }
    },
    "required": ["lat", "lon"]
  },
  "destination": {
    "type": "object",
    "properties": {
      "lat": { "type": "number" },
      "lon": { "type": "number" }
    },
    "required": ["lat", "lon"]
  },
  "via": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "lat": { "type": "number" },
        "lon": { "type": "number" }
      },
      "required": ["lat", "lon"]
    }
  },
  "costing": {
    "type": "string",
    "enum": ["AUTO", "PEDESTRIAN", "BICYCLE", "TRUCK"]
  }
},
"required": ["source", "destination", "costing"]
}

Example Request (cURL)

bash

curl -X POST "https://api.dev.ambalaymaps.com/services/route" \
-H "Content-Type: application/json" \
-H "x-ambalay-key: YOUR_API_KEY" \
-d '{
  "source": { "lat": 8.9806, "lon": 38.7578 },
  "destination": { "lat": 8.9900, "lon": 38.7600 },
  "via": [],
  "costing": "AUTO"
}'

Example Request (JavaScript)

javascript

fetch("https://api.dev.ambalaymaps.com/services/route", {
method: "POST",
headers: {
  "Content-Type": "application/json",
  "x-ambalay-key": API_KEY
},
body: JSON.stringify({
  source: { lat: 8.9806, lon: 38.7578 },
  destination: { lat: 8.9900, lon: 38.7600 },
  via: [],
  costing: "AUTO"
})
})
.then(res => res.json())
.then(data => console.log(data));

Example Request (HTTP)

http

POST /services/route HTTP/1.1
Host: api.dev.ambalaymaps.com
Content-Type: application/json
x-ambalay-key: {API_KEY}

{
"source": { "lat": 8.9806, "lon": 38.7578 },
"destination": { "lat": 8.9900, "lon": 38.7600 },
"via": [],
"costing": "AUTO"
}

Successful Response

json

{
"status": "SUCCESS",
"data": {
  "distanceMeters": 2400,
  "durationSeconds": 540,
  "legs": [
    {
      "summary": "Kazanchis to Bole",
      "steps": [
        {
          "instruction": "Head east toward Bole Road",
          "distanceMeters": 180
        }
      ]
    }
  ]
},
"message": "ROUTE_SUCCESS",
"timestamp": "2026-04-29T06:00:00.000Z",
"requestId": "request-id"
}

Response Fields

Field	Type	Description
`distanceMeters`	number	Total travel distance in meters
`durationSeconds`	number	Total estimated travel time in seconds
`legs`	array	Route segments in travel order
`legs[].summary`	string	Human-readable segment summary
`legs[].steps`	array	Turn-by-turn instructions for the leg
`legs[].steps[].instruction`	string	Navigation instruction text
`legs[].steps[].distanceMeters`	number	Distance covered by the step

Validation Error Example

json

{
"status": "ERROR",
"data": {
  "costing": "costing must be one of AUTO, PEDESTRIAN, BICYCLE, TRUCK"
},
"message": "VALIDATION_ERROR",
"timestamp": "2026-04-29T06:00:00.000Z",
"requestId": "request-id"
}

Common Errors

MISSING_API_KEY
INVALID_API_KEY
API_KEY_SERVICE_NOT_ALLOWED
SERVICE_LIMIT_EXCEEDED
VALIDATION_ERROR

Usage Notes

Use AUTO for standard driving routes
Use PEDESTRIAN for walking routes
Use BICYCLE for cycling routes
Use TRUCK for truck-oriented routing behavior
Do not exceed 10 via points
If the service cannot compute a valid route, the response may be empty or an error may be returned
Clients should explicitly handle “no route found” cases instead of assuming every valid request produces a usable path