Address autocomplete

Suggestions for partial input, tuned for latency and typo tolerance. Every suggestion carries coordinates, so most integrations never need a second call.

Parameters

Example

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/autocomplete?q=oxford+st&proximity=51.515,-0.141&limit=3"

const url = new URL("https://api.mygeocode.com/v1/autocomplete");
url.searchParams.set("q", "oxford st");
url.searchParams.set("proximity", "51.515,-0.141");
url.searchParams.set("limit", "3");

const { suggestions } = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
suggestions.forEach((s) => console.log(s.text, s.lat, s.lon));

import requests

r = requests.get("https://api.mygeocode.com/v1/autocomplete",
                 params={"q": "oxford st", "proximity": "51.515,-0.141", "limit": 3}, headers={"X-API-Key": "YOUR_KEY"}, timeout=5)
for s in r.json()["suggestions"]:
    print(s["text"], s["lat"], s["lon"])

{
  "status": "ok",
  "query": "oxford st",
  "suggestions": [
    {
      "text": "Oxford Street, Greater London, England, United Kingdom",
      "lat": 51.514752,
      "lon": -0.146082,
      "type": "street",
      "precision": "street",
      "place_id": "DHrpomBSMl4-2uI"
    },
    {
      "text": "Oxford Street, Deanend SP5, United Kingdom",
      "lat": 50.956579,
      "lon": -2.037279,
      "type": "street",
      "precision": "street",
      "place_id": "Ls1uaEPX0ASnW4GV8D2W12zd1OQzDdc"
    },
    {
      "text": "Oxford Street, Earl Shilton LE9, United Kingdom",
      "lat": 52.576381,
      "lon": -1.309249,
      "type": "street",
      "precision": "street",
      "place_id": "js3Iw8GnWcYoYUfXZdhMqqVfaaRmZTg"
    }
  ]
}

Response fields

Notes

• Debounce input to around 150 ms and cancel in-flight requests when the user keeps typing. Responses carry the query they answer, so you can discard stale ones.
• There are no session tokens. Each call is one request. A typical address takes 4 to 6 calls to pick.
• Calling from the browser is the intended use for public sites. Without a key, each call counts against the free allowance of the visitor's network. To count your website's calls on your own account, use a browser key.
• The Google places.Autocomplete widget, Mapbox Search Box, HERE Autosuggest and Bing Autosuggest formats are available on the drop-in hosts.

The same lookup in other providers' formats

If you already have code written against one of these providers, keep it: the drop-in host accepts the same path and parameters and answers in that provider's response shape, with this endpoint behind it. See how the drop-ins work.

Errors

400 invalid_request when q is shorter than 2 characters or longer than 128, or when limit is outside 1 to 10. Unknown types values are ignored.