Trips

Trips endpoints let you initialize, update, finalize, and inspect tracked trips.

1. Initialize Trip

Start a new tracked trip. Returns a tripId and initial state.

Method: POST
Path: /services/trip/init
Allowed Service: TRIP
Billed Service: TRIP
Auth: Header x-ambalay-key: {API_KEY}

Request Schema

{
  "type": "object",
  "properties": {
    "loc": {
      "type": "object",
      "properties": {
        "lat": { "type": "number" },
        "lon": { "type": "number" }
      },
      "required": ["lat", "lon"]
    },
    "eventId": { "type": "string" }
  },
  "required": ["loc", "eventId"]
}

Example Request (cURL)

curl -X POST "https://api.dev.ambalaymaps.com/services/trip/init" \
-H "Content-Type: application/json" \
-H "x-ambalay-key: YOUR_API_KEY" \
-d '{
  "loc": { "lat": 8.9806, "lon": 38.7578 },
  "eventId": "evt-1"
}'

Example Request (JavaScript)

fetch('https://api.dev.ambalaymaps.com/services/trip/init', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-ambalay-key': API_KEY,
  },
  body: JSON.stringify({
    loc: { lat: 8.9806, lon: 38.7578 },
    eventId: 'evt-1',
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data))

Success Response

{
  "status": "SUCCESS",
  "data": {
    "tripId": "00000000-0000-4000-8000-000000000020",
    "state": "ACTIVE"
  },
  "message": "TRIP_INIT_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}

data.tripId: Unique trip identifier
data.state: "ACTIVE"

Common Errors

MISSING_API_KEY
INVALID_API_KEY
API_KEY_SERVICE_NOT_ALLOWED
SERVICE_LIMIT_EXCEEDED
VALIDATION_ERROR

Usage Notes

eventId must be unique per request
No idempotency → duplicate eventId may create duplicates
Handle rate limits (SERVICE_LIMIT_EXCEEDED) with retries/backoff

2. Update Trip

Send a new location update for an active trip.

Method: POST
Path: /services/trip/update
Allowed Service: TRIP_UPDATE
Billed Service: TRIP
Auth: Header x-ambalay-key: {API_KEY}

Request Schema

{
  "type": "object",
  "properties": {
    "tripId": { "type": "string" },
    "loc": {
      "type": "object",
      "properties": {
        "lat": { "type": "number" },
        "lon": { "type": "number" }
      },
      "required": ["lat", "lon"]
    },
    "eventId": { "type": "string" }
  },
  "required": ["tripId", "loc", "eventId"]
}

Example Request (cURL)

curl -X POST "https://api.dev.ambalaymaps.com/services/trip/update" \
-H "Content-Type: application/json" \
-H "x-ambalay-key: YOUR_API_KEY" \
-d '{
  "tripId": "00000000-0000-4000-8000-000000000020",
  "loc": { "lat": 8.9810, "lon": 38.7580 },
  "eventId": "evt-2"
}'

Example Request (JavaScript)

fetch('https://api.dev.ambalaymaps.com/services/trip/update', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-ambalay-key': API_KEY,
  },
  body: JSON.stringify({
    tripId: '00000000-0000-4000-8000-000000000020',
    loc: { lat: 8.981, lon: 38.758 },
    eventId: 'evt-2',
  }),
})
  .then((res) => res.json())
  .then((data) => console.log(data))

Success Response

{
  "status": "SUCCESS",
  "data": {
    "tripId": "00000000-0000-4000-8000-000000000020",
    "state": "ACTIVE",
    "accepted": true
  },
  "message": "TRIP_UPDATE_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}

data.accepted: true if update recorded

Usage Notes

Only update active trips
Each eventId must be unique
Avoid excessive calls (rate limits apply)

3. Finalize Trip

End an active trip.

Method: POST
Path: /services/trip/finalize
Allowed Service: TRIP
Billed Service: TRIP
Auth: Header x-ambalay-key: {API_KEY}

Request Schema

{
  "type": "object",
  "properties": {
    "tripId": { "type": "string" },
    "loc": {
      "type": "object",
      "properties": {
        "lat": { "type": "number" },
        "lon": { "type": "number" }
      },
      "required": ["lat", "lon"]
    },
    "eventId": { "type": "string" }
  },
  "required": ["tripId", "loc", "eventId"]
}

Example Request (cURL)

curl -X POST "https://api.dev.ambalaymaps.com/services/trip/finalize" \
-H "Content-Type: application/json" \
-H "x-ambalay-key: YOUR_API_KEY" \
-d '{
  "tripId": "00000000-0000-4000-8000-000000000020",
  "loc": { "lat": 8.9820, "lon": 38.7590 },
  "eventId": "evt-3"
}'

Success Response

{
  "status": "SUCCESS",
  "data": {
    "tripId": "00000000-0000-4000-8000-000000000020",
    "state": "FINALIZED"
  },
  "message": "TRIP_FINALIZE_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}

Usage Notes

Cannot update after finalize
Call only once
eventId must still be unique

4. Trip History

Retrieve all trip events.

Method: GET
Path: /services/trip/history/{tripId}
Allowed Service: TRIP
Billed Service: TRIP
Auth: Header x-ambalay-key: {API_KEY}

Example Request (cURL)

curl "https://api.dev.ambalaymaps.com/services/trip/history/00000000-0000-4000-8000-000000000020" \
-H "x-ambalay-key: YOUR_API_KEY"

Example Request (HTTP)

http

GET /services/trip/history/00000000-0000-4000-8000-000000000020 HTTP/1.1
Host: https://api.ambalaymaps.com
x-ambalay-key: {API_KEY}

Success Response

{
  "status": "SUCCESS",
  "data": {
    "tripId": "00000000-0000-4000-8000-000000000020",
    "state": "FINALIZED",
    "events": [
      {
        "eventId": "evt-1",
        "loc": { "lat": 8.9806, "lon": 38.7578 }
      },
      {
        "eventId": "evt-2",
        "loc": { "lat": 8.981, "lon": 38.758 }
      },
      {
        "eventId": "evt-3",
        "loc": { "lat": 8.982, "lon": 38.759 }
      }
    ]
  },
  "message": "TRIP_HISTORY_SUCCESS",
  "timestamp": "2026-04-29T06:00:00.000Z",
  "requestId": "request-id"
}

Notes

data.events: ordered list of all events
Finalize is reflected via state, not separate event
Use for analytics or visualization

Common Errors

INVALID_API_KEY
MISSING_API_KEY
VALIDATION_ERROR