Quickstart Guide

This quickstart focuses on consuming AmbaLay Maps services from your application after you already have dashboard access and an API key.

1. Choose the allowed services you need

Each API key should only enable the services your integration actually uses.

Common allowed services:

• TILES
• GEO_CODING
• ROUTING
• MATRIX
• TRIP
• TRIP_UPDATE

2. Pick an authentication method

Services support either of these authentication methods:

Header authentication

x-ambalay-key: {API_KEY}

Query authentication

?key={API_KEY}

Use query authentication for browser-based tile clients. Prefer the header for backend and server-to-server requests.

3. Make your first request

This example calls geocoding search.

curl -X GET "https://api.ambalaymaps.com/services/geo_coding/search?term=Addis%20Ababa&limit=5" \
-H "x-ambalay-key: {API_KEY}"

4. Parse the response envelope

Every JSON service returns a standard envelope.

{
  "status": "SUCCESS",
  "data": {
    "items": [
      {
        "id": "place-id",
        "name": "Addis Ababa",
        "label": "Addis Ababa, Ethiopia",
        "loc": {
          "lat": 8.9806,
          "lon": 38.7578
        }
      }
    ]
  },
  "message": "GEO_CODING_SEARCH_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}

When a request fails, use message to decide what to do next.

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

5. Integrate tiles in a browser map client

Tiles are best consumed with query authentication.

https://api.ambalaymaps.com/services/tiles/{z}/{x}/{y}?key={API_KEY}

Successful tile responses return PBF vector tile bytes.

6. Expand to other services

Once the first request works, move to the service-specific docs for:

• Geocoding
• Route
• Matrix
• Trips