Skip to content
Makani Global
Create account
Developers

Address search and reverse lookup

Find addresses by text, by a point on the map or by the country's own address fields.

Base URLhttps://makani-k8s.lamah.com

Autocomplete while typing

Autocomplete suggests addresses while the user is still typing, for a search box or the address field of a checkout. Send what has been typed so far as q (2 to 160 characters) to GET /v1/addresses/{countryCode}/autocomplete. The last word is matched as the start of a word, in Arabic or English, and one typing mistake is forgiven. limit is 5 by default and 10 at most, and the key needs the addresses:search scope.

GET/v1/addresses/{countryCode}/autocompleteScopeaddresses:search
curl "https://makani-k8s.lamah.com/v1/addresses/QA/autocomplete?q=street%2098&locale=en&lat=25.2865&lng=51.5243&limit=5&session=0b0e7d0c-6f0e-4f43-9b7e-2f1f3c1d9a10" \  -H "x-api-key: $MAKANI_API_KEY"

The answer holds suggestions, best first. Each one has its id, its publicCode, a primary line (the formatted address in the locale), a secondary line when the building has a name, its point, and distanceMeters when you sent a point to search around. highlights says where the query shows in primary, as ranges of offset and length counted the way String.slice counts, in order and never overlapping; secondaryHighlights does the same for secondary. Mark those ranges in your list rather than matching the text yourself.

  • Wait before you send. Send a request 250 to 300 ms after the last keystroke, and nothing under 2 characters: a shorter q is refused with 400 VALIDATION_FAILED.
  • Cancel what is stale. When a new request starts, cancel the one still in flight or ignore its answer. An older answer must never replace a newer one.
  • Prefer what is near. Send lat and lng together to put nearer addresses first, and bounds as west,south,east,north to keep only the addresses inside the map's viewport.
  • Know what answered. Suggestions come from a search index, with the registry as the fallback. The X-Search-Source response header says which: index or registry.

A typed search is charged once, not once per keystroke. Generate a UUID when the user starts typing and send it as session with every request of that search. The requests of one session are charged as one unit of the addresses product, for three minutes or until the session is ended. Without session, each request is charged. Rate limits count every request either way.

When the user picks a suggestion, send its id and the session to POST /v1/addresses/{countryCode}/autocomplete/select. This ends the session, is never charged, and counts the choice, so the addresses people choose rank higher later. The next search starts a new session with a new UUID.

POST/v1/addresses/{countryCode}/autocomplete/selectScopeaddresses:search
curl -X POST "https://makani-k8s.lamah.com/v1/addresses/QA/autocomplete/select" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "content-type: application/json" \  -d '{    "id": "<suggestion-id>",    "session": "0b0e7d0c-6f0e-4f43-9b7e-2f1f3c1d9a10"  }'

Reverse lookup from a point

Give a latitude and a longitude and get the nearest addresses, nearest first, each with its distanceMeters. radiusMeters is 1,000 by default and 50,000 at most.

confidence is exact when the point is on an address, nearest when the closest one is returned, and none when nothing lies inside the radius. administrativeHierarchy lists the areas that contain the point.

GET/v1/addresses/{countryCode}/resolveScopeaddresses:resolve
curl "https://makani-k8s.lamah.com/v1/addresses/QA/resolve?latitude=25.2854&longitude=51.531&radiusMeters=1000&locale=en" \  -H "x-api-key: $MAKANI_API_KEY"

Lookup by address fields

When you already have the address as the country writes it, send its fields as query parameters. The fields are the country's own (for Qatar: zone, street and building); GET /v1/countries/{countryCode}/config lists them for any country.

matchCount says how many addresses match; an exact address gives one.

GET/v1/addresses/{countryCode}/lookupScopeaddresses:read
curl "https://makani-k8s.lamah.com/v1/addresses/QA/lookup?locale=en&zone=3&street=984&building=2" \  -H "x-api-key: $MAKANI_API_KEY"

Many lookups in one request

Send up to 100 lookups at once. The answers come back in the order you sent them, and each item counts as one request.

POST/v1/addresses/{countryCode}/lookup/batchScopeaddresses:read
curl -X POST "https://makani-k8s.lamah.com/v1/addresses/QA/lookup/batch" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "content-type: application/json" \  -d '{    "locale": "en",    "requests": [      {        "components": {          "zone": "3",          "street": "984",          "building": "2"        }      },      {        "components": {          "zone": "60",          "street": "900",          "building": "12"        }      }    ]  }'