Matrix API

Calculate travel distance and duration between multiple points.

Method: POST
Base URL: https://api.dev.ambalaymaps.com
Path: /services/matrix
Allowed Service: MATRIX
Billed Service: MATRIX
Authentication: Header x-ambalay-key: {API_KEY}
Content-Type: application/json

Executive Summary

The Matrix endpoint calculates travel distance and duration for multiple origin-destination pairs in a single request.

It is used for:

• ETA comparison
• Nearest-location ranking
• Dispatch optimization
• Batch travel-time analysis

Base URL

https://api.ambalaymaps.com

Endpoint

• Method: POST
• Path: /services/matrix
• Allowed Service: MATRIX
• Billed Service: MATRIX

Authentication

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

Request Body

Point Object

Rules

• sources: up to 50 points
• targets: up to 50 points
• At least one source and one target required
• Supports:
  • 1 → N
  • N → 1
• costing currently only AUTO

Example Request (cURL)

curl -X POST "https://api.ambalaymaps.com/services/matrix" \
-H "Content-Type: application/json" \
-H "x-ambalay-key: YOUR_API_KEY" \
-d '{
"sources": [
  { "lat": 8.9806, "lon": 38.7578 }
],
"targets": [
  { "lat": 8.9900, "lon": 38.7600 },
  { "lat": 9.0100, "lon": 38.7800 }
],
"costing": "AUTO"
}'

Example Request (JavaScript)

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

Successful Response

{
  "status": "SUCCESS",
  "data": {
    "items": [
      {
        "sourceIndex": 0,
        "targetIndex": 0,
        "distanceMeters": 2400,
        "durationSeconds": 540
      },
      {
        "sourceIndex": 0,
        "targetIndex": 1,
        "distanceMeters": 5100,
        "durationSeconds": 980
      }
    ]
  },
  "message": "MATRIX_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}