Lokate
Get API keys
Documentation

API reference

A clean REST API for address autocomplete, geocoding and distance. Authenticate with your secret key, then call any endpoint. Every response is JSON.

Building an AI agent or integration? A plain-text version of these docs lives at /llms.txt.

Base URL

https://app.uselokate.com

Authentication

Pass your API key in the x-api-key header on every request. Each successful call draws from your wallet balance; the balance field on every response is your remaining balance in kobo (₦1 = 100 kobo).

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

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 selected suggestion.

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 → 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

{
  "status": "success",
  "cached": false,
  "balance": 49787,
  "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"
  }
}
POST/v1/distance

Road distance + ETA between two points.

Params: origin {lat,lng}, destination {lat,lng}, transportMode (optional, default car — one of: car, truck, pedestrian, bicycle, scooter, taxi, bus, privateBus)

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

Errors return a non-2xx status with a JSON body of the shape { "status": "error", "message": "..." }.

400 — Bad request (missing or invalid params)

{
  "status": "error",
  "message": "query is required"
}

402 — Insufficient wallet balance

{
  "status": "error",
  "message": "Insufficient wallet balance"
}

401 — Missing or invalid API key

{
  "status": "error",
  "message": "Invalid API key"
}

Try it live

Paste an API key from your dashboard and make a real request.

Enter an API key from your dashboard to try it live.

GET /v1/autocomplete?query=&country=
// response will appear here