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>

Limiting results to within a bounding box #

Filtering by a bounding box is useful if you have your own bounding boxes, or want to filter over an area that’s difficult to represent with a single administrative area via boundary.gid.

See our docs on the four parameters you must pass to use boundary.rect.

For example, to filter to results near only Nice, France and Monaco (two completely separate countries!), use something like the following:

<ge-autocomplete
  api_key="ge-3bad5ca64898357d"
  boundary.rect.min_lon="7.09"
  boundary.rect.max_lon="7.51"
  boundary.rect.min_lat="43.61"
  boundary.rect.max_lat="43.82"
  size="5"
  placeholder="Search for places near Nice and Monaco"
></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.