Services Overview

The /services/* APIs are authenticated with an API key and billed against subscription usage.

Base URL

text
https://api.ambalaymaps.com

Supported Authentication Methods

Header Authentication

http
x-ambalay-key: {API_KEY}

Query Authentication

text
?key={API_KEY}

Use query authentication for browser-driven tile clients. Prefer the request header for server-side integrations.

Service Usage Rules

  • A request succeeds only if the API key is valid and the account has remaining subscription quota
  • Allowed services control which /services/* endpoints an API key can access
  • Quota is consumed before the service handler runs

Authentication Pipeline

  1. API key exists in the header or query string, otherwise MISSING_API_KEY
  2. API key matches a stored key, otherwise INVALID_API_KEY
  3. API key is not expired, otherwise EXPIRED_API_KEY
  4. API key is not revoked, otherwise REVOKED_API_KEY
  5. API key includes the required allowed service, otherwise API_KEY_SERVICE_NOT_ALLOWED
  6. The active subscription has remaining usage for the billed service, otherwise SERVICE_LIMIT_EXCEEDED
  7. The request payload or query params are valid, otherwise VALIDATION_ERROR

Service Reference

ServiceAllowed ServiceBilled ServiceAuth MethodTypical HTTP Status Codes
Trips (init)TRIPTRIPHeader x-ambalay-key200, 400, 401, 403, 429
Trips (update)TRIP_UPDATETRIPHeader x-ambalay-key200, 400, 401, 403, 429
Trips (finalize)TRIPTRIPHeader x-ambalay-key200, 400, 401, 403, 429
Trips (history)TRIPTRIPHeader x-ambalay-key200, 400, 401, 403, 429
MatrixMATRIXMATRIXHeader x-ambalay-key200, 400, 401, 403, 429
RouteROUTINGROUTINGHeader x-ambalay-key200, 400, 401, 403, 429
Geocoding (search)GEO_CODINGGEO_CODINGHeader x-ambalay-key200, 400, 401, 403, 429
Geocoding (reverse)GEO_CODINGGEO_CODINGHeader x-ambalay-key200, 400, 401, 403, 429
TilesTILESTILESHeader x-ambalay-key or query200 (OK, tile), 401, 429

All responses include a JSON status and message.

Typical Meanings

  • 401 Unauthorized → Missing or invalid API key
  • 429 Too Many Requests → Rate limit exceeded
  • 400 Bad Request → Validation error

Response Envelope

Success

json
{
"status": "SUCCESS",
"data": {},
"message": "SOME_SUCCESS_CODE",
"timestamp": "2026-04-29T06:00:00.000Z",
"requestId": "request-id"
}

Error

json
{
"status": "ERROR",
"message": "ERROR_CODE",
"timestamp": "2026-04-29T06:00:00.000Z",
"requestId": "request-id"
}