# Lokate — Address & Maps API

> REST API for address autocomplete, geocoding, reverse geocoding and distance,
> built for African businesses. Pay as you go from a prepaid wallet. Every
> response is JSON. This file is a plain-text mirror of https://app.uselokate.com/docs
> for AI agents and crawlers.

Base URL: https://app.uselokate.com

## Authentication

Pass your API key in the `x-api-key` header on every request.

    curl "https://app.uselokate.com/v1/autocomplete?query=Lekki&country=NG" \
      -H "x-api-key: mak_live_xxxxxxxx"

Keys come in `mak_live_` and `mak_test_` prefixes. Create them in the dashboard.

## Response envelope

Every successful (200) response has this shape:

    {
      "status": "success",
      "cached": <boolean>,   // true if served from cache (cheaper)
      "balance": <integer>,  // remaining wallet balance in KOBO (₦1 = 100)
      "data": <object|array> // the result, shape depends on the endpoint
    }

## Pricing (charged per successful call, in kobo)

- autocomplete: ₦2.00
- place detail: ₦3.00
- reverse-geocode: ₦8.00
- distance: ₦8.00
- any cache hit: ₦1.00

Failed provider calls are not charged (the wallet is refunded automatically).

## Endpoints

### GET /v1/autocomplete

Address suggestions as the user types.

Params: `query` (required), `country` (optional, ISO 3166-1 alpha-2, e.g. NG)

Request:

    curl "https://app.uselokate.com/v1/autocomplete?query=Lekki&country=NG" \
      -H "x-api-key: mak_live_xxxxxxxx"

Response 200:

    {
      "status": "success",
      "cached": false,
      "balance": 49798,
      "data": [
        {
          "placeId": "ChIJ0SfgT9k6OxARrm9o2zEh3lA",
          "mainText": "Lekki Phase 1",
          "secondaryText": "Lagos, Nigeria",
          "description": "Lekki Phase 1, Lagos, Nigeria",
          "countryCode": "NG"
        }
      ]
    }

### GET /v1/place/:placeId

Full structured address + lat/lng for a suggestion returned by autocomplete.

Params: `placeId` (path, required), `mainText` (optional)

Request:

    curl "https://app.uselokate.com/v1/place/ChIJ0SfgT9k6OxARrm9o2zEh3lA" \
      -H "x-api-key: mak_live_xxxxxxxx"

Response 200:

    {
      "status": "success",
      "cached": false,
      "balance": 49795,
      "data": {
        "address": "12 Admiralty Way",
        "city": "Lagos",
        "state": "Lagos",
        "country": "NG",
        "postCode": "106104",
        "lat": 6.4474,
        "lng": 3.4736,
        "formatted": "12 Admiralty Way, Lekki Phase 1, Lagos, Nigeria"
      }
    }

### GET /v1/reverse-geocode

Coordinates to a human-readable address.

Params: `lat` (required), `lng` (required)

Request:

    curl "https://app.uselokate.com/v1/reverse-geocode?lat=6.4474&lng=3.4736" \
      -H "x-api-key: mak_live_xxxxxxxx"

Response 200: same `data` shape as /v1/place/:placeId.

### POST /v1/distance

Road distance + ETA between two points.

Body (JSON): `origin` {lat,lng}, `destination` {lat,lng}, `transportMode` (optional,
default "car" — one of: car, truck, pedestrian, bicycle, scooter, taxi, bus, privateBus).
The ETA is calculated for the chosen mode, so the same route returns different durations
for e.g. car vs truck vs pedestrian.

Request:

    curl -X POST "https://app.uselokate.com/v1/distance" \
      -H "x-api-key: mak_live_xxxxxxxx" \
      -H "Content-Type: application/json" \
      -d '{"origin":{"lat":6.4474,"lng":3.4736},"destination":{"lat":6.6018,"lng":3.3515},"transportMode":"car"}'

Response 200:

    {
      "status": "success",
      "cached": false,
      "balance": 49779,
      "data": {
        "meters": 28640,
        "km": 28.64,
        "seconds": 3120,
        "minutes": 52,
        "durationText": "52 min"
      }
    }

## Errors

All errors return `{ "status": "error", "message": "..." }` with a non-2xx status.

- 400 — bad request, e.g. `{ "status": "error", "message": "query is required" }`
- 401 — missing/invalid key, e.g. `{ "status": "error", "message": "Invalid API key" }`
- 402 — `{ "status": "error", "message": "Insufficient wallet balance" }` (top up the wallet)
- 500 — `{ "status": "error", "message": "Something went wrong processing your request" }`