Autocomplete

https://api.geocode.earth/v1/autocomplete

The autocomplete endpoint is purpose built for handling geocoding requests coming directly from end-users.

With fast response times and support for partially complete input, the autocomplete endpoint is perfect for building responsive user interfaces. This is often known as autosuggest or search-as-you-type.

These interfaces often take the form of address or POI drop down/select menus, like the one shown below.

Because the autocomplete endpoint is central to the actual experience of end users, be sure to read our UX Best Practices and Performance Best Practices to make sure you’re getting the most out of it.

Better yet, use one of our guides and libraries that follow all our best practices out of the box:

Basic usage #

The autocomplete endpoint requires, at minimum, a text parameter, which should generally be filled by text from a search box typed by an end user.

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=$api_key \
  -d text=lond

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "text=lond"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # London
puts response['features'][0]['properties']['label']     # London, England, United Kingdom
puts response['features'][0]['geometry']['coordinates'] # [ -0.099076, 51.509648 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/autocomplete?' +
              `api_key=${api_key}&` +
              'text=lond';

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

    console.log(response['features'][0]['properties']['name']);      // London
    console.log(response['features'][0]['properties']['label']);     // London, England, United Kingdom
    console.log(response['features'][0]['geometry']['coordinates']); // [ -0.099076, 51.509648 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?" \
        "api_key="+api_key+"&"\
        "text=lond"

response = json.load(urllib.request.urlopen(query))

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # London
print(response['features'][0]['properties']['label'])     # London, England, United Kingdom
print(response['features'][0]['geometry']['coordinates']) # [ -0.099076, 51.509648 ]

Filtering parameters #

The autocomplete endpoint supports all forward geocoding filtering parameters.

For example, you might want to prefer results near a particular longitude and latitude coordinate, and limit results to Points of Interest (the venue layer):

Shell Ruby Node.js Python
api_key='<YOUR API KEY>'

curl --get https://api.geocode.earth/v1/autocomplete \
  -d api_key=$api_key \
  -d focus.point.lat=38.82 \
  -d focus.point.lon=-77.01 \
  -d layers=venue \
  -d text=busboys

require 'net/http'
require 'json'

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key=#{api_key}&"\
        "focus.point.lat=38.82&"\
        "focus.point.lon=-77.01&"\
        "layers=venue&"\
        "text=busboys"
http_response = Net::HTTP.get_response(URI(query))
response = JSON.parse(http_response.body)

puts response # print the entire response

puts response['features'][0]['properties']['name']      # Busboys and Poets
puts response['features'][0]['properties']['label']     # Busboys and Poets, Washington, DC, USA
puts response['features'][0]['geometry']['coordinates'] # [ -77.031697, 38.917929 ]

const https = require('https');

const api_key = '<YOUR API KEY>';
const query = 'https://api.geocode.earth/v1/autocomplete?' +
              `api_key=${api_key}&`     +
              'focus.point.lat=38.82&'  + // Washington DC
              'focus.point.lon=-77.01&' + // Washington DC
              'layers=venue&'           + // filter only for POIs
              'text=busboys';

const req = https.get(query, (res) => {
  let body = '';
  res.on('data', data => { body += data; });

  res.on('end', () => {
    const response = JSON.parse(body);
    console.log(response); // print the entire response

    console.log(response['features'][0]['properties']['name']);      // Busboys and Poets
    console.log(response['features'][0]['properties']['label']);     // Busboys and Poets, Washington, DC, USA
    console.log(response['features'][0]['geometry']['coordinates']); // [ -77.031697, 38.917929 ]
  });
}).end();

import json
import urllib.request

api_key = '<YOUR API KEY>'
query = "https://api.geocode.earth/v1/autocomplete?"\
        "api_key="+api_key+"&"\
        "focus.point.lat=38.82&"\
        "focus.point.lon=-77.01&"\
        "layers=venue&"\
        "text=busboys".replace(' ', '+')

response = json.load(urllib.request.urlopen(query))

print(response) # print the entire response

print(response['features'][0]['properties']['name'])      # Busboys and Poets
print(response['features'][0]['properties']['label'])     # Busboys and Poets, Washington, DC, USA
print(response['features'][0]['geometry']['coordinates']) # [ -77.031697, 38.917929 ]

User experience best practices #

Handle out of order responses #

When multiple autocomplete requests are in-flight to Geocode Earth simultaneously, the order responses will be received is not guaranteed.

For example, a user searching for London may cause queries for Lond and London to be sent at nearly the same time. However, the response for Londo may very well come back first (in general, longer text inputs result in faster responses).

Without special handling, results for London may appear briefly, followed by (inferior) results for Lond as the response to the first request comes in later.

To fix this, keep track of which query was sent first, and only display results of queries that were sent more recently than the one currently displayed.

Consider throttling/debouncing requests #

While sending an autocomplete request for every user keystroke is possible, it’s not always recommended. Fast typers can easily create more queries than are reasonable to send, and many networks (especially mobile phones on a poor connection) may not handle many simultaneous requests well.

In general, a limit of 5 to 10 requests per second strikes a good balance between responsiveness and efficiency. This limit will also help avoid hitting Geocode Earth per-second rate limits.

Performance best practices #

Milliseconds matter with the autocomplete endpoint, since there’s an actual human waiting on the result of each query.

The following best practices will help ensure you avoid common performance pitfalls.

Do not proxy the Geocode Earth servers #

Proxying the Geocode Earth API will introduce an unneeded delay as traffic is routed from our servers, to yours, and finally to end users.

Whenever possible, ensure your website or mobile app is calling our API directly.

Also see our documentation on Securing your API Keys.

Use the focus.point parameter #

In addition to providing results that are more relevant due to their proximity, the focus.point parameter is generally significantly faster than an unfocused query.

This is because the focus.point parameter allows us to quickly excluded potential results that are very far away from the focus point, and were already poor matches for the text query.

The value for the focus.point parameter might come from several sources, for example:

  • the geolocation API on a mobile device (fine or coarse location are both acceptable)
  • the center of the currently visible map viewport
  • a GeoIP lookup from a users IP address (least recommended, and Geocode Earth does not do this automatically)

Avoid querying the address layer if you don’t want address results #

The vast majority of records in the Geocode Earth search database are addresses. While address results will generally be excluded when they are very poor matches to the input query, explicitly excluding them can be even faster and more efficient.

To do this, use the layers parameter to specify only layers you are interested in.

You might, for example, want layers=coarse to only return administrative layers (cities, states, countries, etc), or layers=venue to return only venues or other points of interest.

While this advice is technically true everywhere, and you should use the layers parameter to prefer only the types of results you’re interested in, the address layer is most notable due to its large size.