Autocomplete Element

This guide covers how to quickly add a fast, configurable and easy-to-use address autocompletion element to any web app or web page.

In just a few minutes, you’ll have a responsive, interactive <input> element like this:

Installation #

The autocomplete element is available through npm or the traditional <script> tag.

Pre-bundled version via HTML script tag #

We maintain an up to date, minified version of the autocomplete element available via CDN.

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@geocodeearth/autocomplete-element/dist/bundle.js">
</script>

Full Package via NPM #

This option will work best if you’re already using webpack or another tool for managing JavaScript dependencies.

With a modern version of node installed:

npm install @geocodeearth/autocomplete-element --save

import '@geocodeearth/autocomplete-element'

Basic Usage #

To get started, you only need your Geocode Earth API key and one line of HTML.

<ge-autocomplete
  api_key="<YOUR API KEY>"
></ge-autocomplete>

Using Autocomplete endpoint filters #

The autocomplete endpoint supports numerous filtering options, and all of them are supported by the autocomplete element.

Here are a few common examples, each with their own live demo.

Restricting results to a few countries #

The boundary.country parameter allows restricting results to a list of one or more countries.

<ge-autocomplete
  api_key="<YOUR API KEY>"
  boundary.country="US,CA,MX"
  placeholder="Search for places in North America"
></ge-autocomplete>

Preferring results near a lat/lon coordinate #

The focus.point.lat and focus.point.lon allow biasing results to those closer to the given coordinate.

<ge-autocomplete
  api_key="<YOUR API KEY>"
  focus.point.lat="21.30"
  focus.point.lon="-157.85"
  placeholder="Search for places near Honolulu, Hawaii"
></ge-autocomplete>

Restricting results to a single city #

The boundary.gid parameter accepts any parent ID returned by other queries to Geocode Earth.

<ge-autocomplete
  api_key="<YOUR API KEY>"
  boundary.gid="whosonfirst:locality:101748323"
  placeholder="Search for places in Barcelona, Spain"
></ge-autocomplete>

Events #

The HTML element emits events, attaching event listeners allows your application to be notified when the user interacts with the element.

The event.detail payload contains details about each event.

// find the first matching ge-autocomplete element
const el = document.querySelector('ge-autocomplete')

// 'select' event handler - when a user selects an item from the suggestions
el.addEventListener('select', (event) => {
  console.log(event.detail, event)
})

// 'change' event handler - on every keystroke as the user types
el.addEventListener('change', (event) => {
  console.log(event.detail, event)
})

// 'features' event handler - when the GeoJSON features backing the UI change
el.addEventListener('features', (event) => {
  console.log(event.detail, event)
})

// 'error' event handler - on error
el.addEventListener('error', (event) => {
  console.log(event.detail, event)
})

Visual Customization #

The Github documentation outlines a variety of options for customizing the visual appearance of the element:

Feedback & Feature Requests #

If you find a bug, or would like to request a feature, please open an issue on Github.