TypeScript icon, indicating that this package has built-in type declarations

2.0.1 • Public • Published

Geoapify Geocoder Autocomplete

The Geoapify Geocoder Autocomplete is a JavaScript (TypeScript) library designed to enhance web applications and HTML pages by adding advanced address autocomplete functionality and address autofill input fields. It harnesses the power of the Geoapify Geocoding API to provide accurate and efficient address search capabilities, making it an essential tool for enhancing the geolocation services of web-based applications.

Geocoder Autocomplete

  • Customizable Address Input: Easily embed address input fields within your web application by adding them to provided HTML containers (e.g., DIV elements), allowing for flexible integration and styling.
  • API Integration Flexibility: By default, the library seamlessly connects to the Geoapify Address Autocomplete API to retrieve address suggestions. However, developers have the freedom to integrate and combine other third-party Address Search APIs, allowing for extensive customization and the incorporation of multiple data sources.
  • Search Customization: Tailor your address search with precision by adding filters and bias parameters. This level of customization empowers developers to fine-tune search queries, ensuring more accurate and relevant address suggestions for users.
  • Structured Address Forms: Utilize the type parameter to craft address input forms that enable users to enter structured addresses, including postal codes, cities, countries, address lines, and more.
  • Place Details Integration: Optionally, the library can call the Geoapify Place Details API, providing users with detailed city and building boundaries as part of the search results. This enhances location context and visualization for a richer user experience.
  • Customizable Look-and-Feel: Tailor the appearance of the address input and autocomplete suggestions effortlessly. The library offers four distinct styles for both light and dark themes, providing design flexibility. Moreover, developers can further fine-tune the visual aspects using CSS classes to achieve a seamless integration with their application's aesthetics.
  • Zero Dependencies: The library is intentionally built with zero external dependencies. This means that it operates independently and does not rely on external libraries or packages.


JSFiddle demo: Address Field + Map

JSFiddle demo: Address Form 1

JSFiddle demo: Address Form 2

Getting Geoapify API key

In case you decide to use Geoapify API to search addresses, you'll need to obtain an API key.

Register for free and obtain your API key at myprojects.geoapify.com. Geoapify offers a flexible Freemium pricing model that allows you to begin using our services at no cost and seamlessly scale your usage as your needs grow.


Start enhancing your web applications today with @geoapify/geocoder-autocomplete:

Option 1

Install the Geocoder Autocomplete package with NPM or Yarn project manager:

npm install @geoapify/geocoder-autocomplete
# or 
yarn add @geoapify/geocoder-autocomplete

Option 2

Refer to the Geocoder Autocomplete library as a UMD module (for CMS websites, including WordPress):

        <script src=".../index.min.js"></script>
        <link rel="stylesheet" type="text/css" href=".../minimal.css">

You can use UNPKG to refer or download the library:



Using @geoapify/geocoder-autocomplete in your project

Follow the steps below to seamlessly integrate @geoapify/geocoder-autocomplete into your project.

STEP 1. Prepare your webpage

Incorporate a container element into your webpage where the autocomplete input will be seamlessly integrated, utilizing the full width of the specified element:

<div id="autocomplete" class="autocomplete-container"></div>

The container element must have position: absolute or position: relative

.autocomplete-container {
    position: relative;

STEP 2. Initialize the autocomplete field

  • Option 1. Import the Geocoder Autocomplete types when you use it as a module:
import { GeocoderAutocomplete } from '@geoapify/geocoder-autocomplete';

const autocomplete = new GeocoderAutocomplete(
                        { /* Geocoder options */ });

autocomplete.on('select', (location) => {
    // check selected location here 

autocomplete.on('suggestions', (suggestions) => {
    // process suggestions here
  • Option 2. Refer to the Geocoder Autocomplete as autocomplete when you added it as a script:
const autocompleteInput = new autocomplete.GeocoderAutocomplete(
                        { /* Geocoder options */ });

autocompleteInput.on('select', (location) => {
    // check selected location here 

autocompleteInput.on('suggestions', (suggestions) => {
    // process suggestions here

STEP 3. Add the Autocomplete Input styles:

We provide several Themes within the library:

  • minimal and round-borders - for webpages with light background color
  • minimal-dark and round-borders-dark for webpages with dark background color.

You can import the appropriate css-file to your styles:

 @import "~@geoapify/geocoder-autocomplete/styles/minimal.css";

or as a link in a HTML-file:

<link rel="stylesheet" type="text/css" href="https://unpkg.com/@geoapify/geocoder-autocomplete@^1/styles/minimal.css">

Transitioning from 1.x: Replacing skipDetails with addDetails

When transitioning from the 1.x version of the library to the 2.x version, it's important to note that the skipDetails option has been replaced by the addDetails option. This change enhances the clarity of the parameter, as it now explicitly indicates whether you want to include or exclude additional details in the search results. To maintain compatibility with the updated version, make sure to adjust your code accordingly by using the addDetails option when needed for your address search functionality.

So, if you require place details in your search results, you should set the addDetails option to true.


Below, you'll find @geoapify/geocoder-autocomplete's detailed documentation, usage examples, advanced features, and more. You'll find the information you need to seamlessly integrate address autocomplete and enhance your web-based geolocation services and user experiences.


Option Type Description
constructor GeocoderAutocomplete( el, geoapifyApiKey, options?) GeocoderAutocomplete(document.getElementById('autocomplete'), 'sdf45dfg68879fhsdgs346dfhdj', { lang: 'it' }


Option Type Description
type country, state, city, postcode, street, amenity Type of the location
lang LanguageCode Results language
limit number The maximal number of returned suggestions
placeholder string An input field placeholder
debounceDelay number A delay between user input and the API call to prevent unnecessary calls. The default value is 100ms.
skipIcons boolean Don't add icons to suggestions
addDetails boolean Call Place Details API on selection change to get the place details. For example, opening hours or boundary
skipSelectionOnArrowKey boolean Don't choose the location with the arrow keys
filter FilterOptions Filter places by country, boundary, circle, place
bias BiasOptions Prefer places by country, boundary, circle, location
allowNonVerifiedHouseNumber boolean Allow the addition of house numbers that are not verified by the Geocoding API or missing in the database. Check the "Working with non-verified values" section for details.
allowNonVerifiedStreet boolean Allow the addition of streets that are not verified by the Geocoding API or missing in the database. Check the "Working with non-verified values" section for details.


2-character ISO 639-1 language code: ab, aa, af, ak, sq, am, ar, an, hy, as, av, ae, ay, az, bm, ba, eu, be, bn, bh, bi, bs, br, bg, my, ca, ch, ce, ny, zh, cv, kw, co, cr, hr, cs, da, dv, nl, en, eo, et, ee, fo, fj, fi, fr, ff, gl, ka, de, el, gn, gu, ht, ha, he, hz, hi, ho, hu, ia, id, ie, ga, ig, ik, io, is, it, iu, ja, jv, kl, kn, kr, ks, kk, km, ki, rw, ky, kv, kg, ko, ku, kj, la, lb, lg, li, ln, lo, lt, lu, lv, gv, mk, mg, ms, ml, mt, mi, mr, mh, mn, na, nv, nb, nd, ne, ng, nn, no, ii, nr, oc, oj, cu, om, or, os, pa, pi, fa, pl, ps, pt, qu, rm, rn, ro, ru, sa, sc, sd, se, sm, sg, sr, gd, sn, si, sk, sl, so, st, es, su, sw, ss, sv, ta, te, tg, th, ti, bo, tk, tl, tn, to, tr, ts, tt, tw, ty, ug, uk, ur, uz, ve, vi, vo, wa, cy, wo, fy, xh, yi, yo, za.


The Geocoder Autocomplete allows specify the following types of filters:

Name Filter Filter Value Description Examples
By circle circle { lon: number ,lat: number, radiusMeters: number } Search places inside the circle filter['circle'] = {lon: -87.770231, lat: 41.878968, radiusMeters: 5000}
By rectangle rect { lon1: number ,lat1: number, lon2: number ,lat2: number} Search places inside the rectangle filter['rect'] = {lon1: 89.097540, lat1: 39.668983, lon2: -88.399274, lat2: 40.383412}
By country countrycode CountyCode[] Search places in the countries filter['countrycode'] = ['de', 'fr', 'es']
By place place string Search for places within a given city or postal code. For example, search for streets within a city. Use the 'place_id' returned by another search to specify a filter. filter['place'] = '51ac66e77e9826274059f9426dc08c114840f00101f901dcf3000000000000c00208'

You can provide filters as initial options or add by calling a function:

    options.filter = {
        'circle': {lon: -87.770231, lat: 41.878968, radiusMeters: 5000}

    // or

    autocomplete.addFilterByCircle({lon: -87.770231, lat: 41.878968, radiusMeters: 5000});

You can combine several filters (but only one of each type) in one request. The AND logic is applied to the multiple filters.


You can chage priority of the search by setting bias. The Geocoder Autocomplete allows specify the following types of bias:

Name Bias Bias Value Description Examples
By circle circle { lon: number ,lat: number, radiusMeters: number } First, search places inside the circle, then worldwide bias['circle'] = {lon: -87.770231, lat: 41.878968, radiusMeters: 5000}
By rectangle rect { lon1: number ,lat1: number, lon2: number ,lat2: number} First, search places inside the rectangle, then worldwide bias['rect'] = {lon1: 89.097540, lat1: 39.668983, lon2: -88.399274, lat2: 40.383412}
By country countrycode CountyCode[] First, search places in the countries, then worldwide bias['countrycode'] = ['de', 'fr', 'es']
By location proximity {lon: number ,lat: number} Prioritize results by farness from the location bias['proximity'] = {lon: -87.770231, lat: 41.878968}

You can combine several bias parameters (but only one of each type) in one request. The OR logic is applied to the multiple bias.

NOTE! The default bias for the geocoding requests is "countrycode:auto", the API detects a country by IP address and provides the search there first. Set bias['countrycode'] = ['none'] to avoid prioritization by country.

You can provide filters as initial options or add by calling a function:

    options.bias = {
        'circle': {lon: -87.770231, lat: 41.878968, radiusMeters: 5000},
        'countrycode': ['none']

    // or

    autocomplete.addBiasByCircle({lon: -87.770231, lat: 41.878968, radiusMeters: 5000});


  • Use 'auto' to detect the country by IP address;
  • Use 'none' to skip;
  • 2-digits ISO 3166-1 Alpha-2 country code: ad, ae, af, ag, ai, al, am, an, ao, ap, aq, ar, as, at, au, aw, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bm, bn, bo, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ci, ck, cl, cm, cn, co, cr, cu, cv, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, eu, fi, fj, fk, fm, fo, fr, ga, gb, gd, ge, gf, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, in, io, iq, ir, is, it, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, st, sv, sy, sz, tc, td, tf, tg, th, tj, tk, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, um, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, ye, yt, za, zm, zw.

Learn more about Geoapify Geocoder options on Geoapify Documentation page.


Here's a description of the API methods:

Method Description
setType(type: 'country' or 'state' or 'city' or 'postcode' or 'street' or 'amenity'): void Sets the type of location for address suggestions.
setLang(lang: SupportedLanguage): void Sets the language for address suggestions.
setCountryCodes(codes: CountyCode[]): void Sets specific country codes to filter address suggestions.
setPosition(position: GeoPosition = {lat: number; lon: number}): void Sets the geographic position to influence suggestions based on proximity.
setLimit(limit: number): void Sets the maximum number of suggestions to display.
setValue(value: string): void Sets the value of the input field programmatically.
getValue(): string Retrieves the current value of the input field.
addFilterByCountry(codes: CountyCode[]): void Adds a filter to include or exclude suggestions based on specific country codes.
addFilterByCircle(filterByCircle: ByCircleOptions = {lon: number; lat: number; radiusMeters: number }): void Adds a circular filter to include or exclude suggestions within a specified geographic area.
addFilterByRect(filterByRect: ByRectOptions = { lon1: number; lat1: number; lon2: number; lat2: number}): void Adds a rectangular filter to include or exclude suggestions within a specified geographic area.
addFilterByPlace(filterByPlace: string): void Adds a filter to include or exclude suggestions based on a specific place or location.
clearFilters(): void Clears all previously added filters.
addBiasByCountry(codes: CountyCode[]): void Adds a bias to prioritize suggestions from specific countries.
addBiasByCircle(biasByCircle: ByCircleOptions = {lon: number; lat: number; radiusMeters: number }): void Adds a circular bias to prioritize suggestions within a specified geographic area.
addBiasByRect(biasByRect: ByRectOptions = { lon1: number; lat1: number; lon2: number; lat2: number}): void Adds a rectangular bias to prioritize suggestions within a specified geographic area.
addBiasByProximity(biasByProximity: ByProximityOptions = { lon: number; lat: number }): void Adds a bias based on proximity to a specific location.
clearBias(): void Clears all previously added biases.
setSuggestionsFilter(suggestionsFilterFunc?: (suggestions: GeoJSON.Feature[]) => GeoJSON.Feature[]): void Sets a custom filter function for suggestions.
setPreprocessHook(preprocessHookFunc?: (value: string) => string): void Sets a preprocessing hook to modify the input value before sending a request.
setPostprocessHook(postprocessHookFunc?: (value: string) => string): void Sets a post-processing hook to modify the suggestion values after retrieval.
isOpen(): boolean Checks if the suggestions dropdown is currently open.
close(): void Manually closes the suggestions dropdown.
open(): void Manually opens the suggestions dropdown.
sendGeocoderRequest(value: string): Promise<GeoJSON.FeatureCollection> Sends a geocoder request based on the provided value and returns a Promise with the response in GeoJSON FeatureCollection format containing suggestions.
sendPlaceDetailsRequest(feature: GeoJSON.Feature): Promise<GeoJSON.Feature> Sends a place details request based on the provided GeoJSON feature and returns a Promise with the response in GeoJSON Feature format containing place details.
setSendGeocoderRequestFunc(sendGeocoderRequestFunc: (value: string, geocoderAutocomplete: GeocoderAutocomplete) => Promise<GeoJSON.FeatureCollection>): void Sets a custom function to send geocoder requests.
setSendPlaceDetailsRequestFunc(sendPlaceDetailsRequestFunc: (feature: GeoJSON.Feature, geocoderAutocomplete: GeocoderAutocomplete) => Promise<GeoJSON.Feature>): void Sets a custom function to send place details requests.
on(operation: 'select' or 'suggestions' or 'input' or 'close' or 'open', callback: (param: any) => void): void Attaches event listeners to various operations such as selection, suggestions, input changes, and dropdown open/close.
off(operation: 'select' or 'suggestions' or 'input' or 'close' or 'open', callback?: (param: any) => void): void Detaches previously attached event listeners.
once(operation: 'select' or 'suggestions' or 'input' or 'close' or 'open', callback: (param: any) => void): void Attaches a one-time event listener that triggers only once for the specified operation.

Example. Setting Geocoder options

The library offers a flexible API that enables the dynamic configuration of Geoapify Geocoder options at runtime:

const autocomplete = new GeocoderAutocomplete(...);

// set location type
// set results language
// set dropdown elements limit

// set filter

// set bias

Example. Close and open the suggestions dropdown automatically

You can also interact with the suggestions dropdown through the API, allowing you to check its current state and toggle the open/close state as needed:

// get and change dropdown list state

Example. Setting and getting the display value

You have the ability to retrieve the current value or modify the displayed value:


const displayValue = autocomplete.getValue();

Example. Hooks and suggestions filter

Through the inclusion of preprocessing and post-processing hooks, as well as a suggestions filter, you modify both the entered values before sending the request and the received suggestions list:

  • Preprocess Hook - Empower your address search by modifying the input text dynamically. For instance, when expecting a street name, you can enhance the search by adding a city or postcode to find streets within that specific location.
  • Postprocess Hook - Tailor the displayed text in both the input field and suggestions list to match your desired format. For example, you can choose to display only the street name, offering a cleaner and more user-friendly presentation.
  • Suggestions Filter - Efficiently manage and filter suggestions to prevent duplication or remove unnecessary items. This feature is particularly useful when applying a post-process hook, ensuring that suggestions with identical street names are intelligently handled and presented without redundancy.
// add preprocess hook
autocomplete.setPreprocessHook((value: string) => {
    // return augmented value here
    return `${value} ${someAdditionalInfo}`

// remove the hook

autocomplete.setPostprocessHook((feature) => {
    // feature is GeoJSON feature containing structured address
    // return a part of the address to be displayed
    return feature.properties.street;

// remove the hook

autocomplete.setSuggestionsFilter((features: any[]) => {
    // features is an array of GeoJSON features, that contains suggestions
    // return filtered array
    const processedStreets = [];
    const filtered = features.filter(feature => {
        if (!feature.properties.street || processedStreets.indexOf(feature.properties.street) >= 0) {
            return false;
        } else {
            return true;
    return filtered;

// remove the filter

Example. Overwrite send request method

The library provides the flexibility to override default API methods, with Geoapify API being the default choice, for searching addresses. This allows you to seamlessly integrate custom or third-party address search services, offering you the freedom to tailor the geocoding functionality to your specific needs.

Here is an example of how you can override the default API methods to integrate custom or third-party address search services:

autocomplete.setSendGeocoderRequestFunc((value: string, geocoderAutocomplete: GeocoderAutocomplete) => {

  if (/* check here if you can geocode the value */) {
    return new Promise((resolve, reject) => {
        "type": "FeatureCollection",
        "features": [
            "type": "Feature",
            "properties": {
            "formatted": address
          "geometry": {
            "type": "Point",
            "coordinates": [lon, lat]

  // You can call the default search method this way
  return geocoderAutocomplete.sendGeocoderRequest(value);

autocomplete.setSendPlaceDetailsRequestFunc((feature: any, geocoderAutocomplete: GeocoderAutocomplete) => {
  if (/* you have details for the place */) {
    return new Promise((resolve, reject) => {
        "type": "FeatureCollection",
        "features": [
            "type": "Feature",
            "properties": {
            "formatted": address
          "geometry": { ... }

  // You can call the default place details method this way
  return geocoderAutocomplete.sendPlaceDetailsRequest(feature);


@geoapify/geocoder-autocomplete provides a set of event handling functions—on, off, and once. These functions allow you to attach, detach, and manage event listeners for various user interactions and changes within the library.

Event Name Description
select Triggered when a suggestion is selected from the dropdown. Useful for capturing and responding to user selections.
suggestions Fired when suggestions are provided, allowing access to the list of suggestions for customization or interaction.
input Occurs whenever the input field value changes, providing real-time feedback on user input for dynamic adjustments.
close Triggered when the suggestions dropdown is closed, enabling actions to be performed when the dropdown closes.
open Fired when the suggestions dropdown is opened, offering an opportunity to respond to dropdown opening events.

These events offer flexibility and customization options for creating tailored interactions and user experiences in your application.

Example. Geocoder Autocomplete events

You have the option to attach event listeners to the Geocoder Autocomplete:

autocomplete.on('select', (location) => {
    // check selected location here 

autocomplete.on('suggestions', (suggestions) => {
    // process suggestions here

autocomplete.on('input', (userInput) => {
    // process user input here

autocomplete.on('open', () => {
    // dropdown list is opened 

autocomplete.on('close', () => {
    // dropdown list is closed 

autocomplete.once('open', () => {
    // dropdown list is opened, one time callback

autocomplete.once('close', () => {
    // dropdown list is closed, one time callback

The location have GeoJSON.Feature type, suggestions have GeoJSON.Feature[] type. The feature properties contain information about address and location.

Use off() function to remove event listerers:

// remove open event
autocomplete.off('open', this.onOpen);

// remove all open events

Learn more about Geocoder result properties on Geoapify Documentation page.


We offer a variety of built-in themes within the library, catering to different webpage styles:

  1. Minimal Theme: Designed for webpages with a light background color.
  2. Round Borders Theme: Tailored for webpages with a light background color, featuring rounded borders.
  3. Minimal Dark Theme: Ideal for webpages with a dark background color.
  4. Round Borders Dark Theme: Specifically crafted for webpages with a dark background color, incorporating rounded borders.

These themes offer versatile styling options to seamlessly integrate the address autocomplete component into various webpage designs.

Moreover, if you prefer to have complete control over the styling, you have the opportunity to customize the component yourself. Below are the CSS classes used for styling:

Class Name Description
.geoapify-autocomplete-input Styles the input element.
.geoapify-autocomplete-items Styles the dropdown list.
.geoapify-autocomplete-items .active Styles the selected item in the dropdown list.
.geoapify-autocomplete-item Styles the individual dropdown list items.
.geoapify-autocomplete-item.icon Styles the icon within the dropdown list items.
.geoapify-autocomplete-item.text Styles the text within the dropdown list items.
.geoapify-close-button Styles the clear button.
.geoapify-autocomplete-items .main-part .non-verified Styles a portion of the street address that could not be verified by the Geocoder.

Working with non-verified address components

When utilizing the Geocoder Autocomplete library to gather postal addresses, it's often advantageous to adopt a more permissive approach, allowing for the inclusion of non-verified address components such as house numbers and streets.

In real-world scenarios, it's possible that newly constructed streets or houses may not yet be included in existing databases. Restricting users from entering such addresses may not align with your objectives.

To accommodate users and enable the inclusion of non-verified address parts, you can leverage the allowNonVerifiedHouseNumber and allowNonVerifiedStreet parameters. These settings empower users to contribute address details that may not yet be officially validated, fostering flexibility and completeness in your address data collection process.

How it works

The library operates by utilizing the API to retrieve essential address details, including the parsed address, the located address, and a match type as results. Using this information as a foundation, the library enhances the result by filling in missing values, such as house numbers, to provide a more complete and user-friendly address representation.

Notably, non-verified address components are denoted with a "non-verified" class, making them visually distinct by default, often highlighted in red to indicate their provisional or unverified status.

It's essential to note that the GPS coordinates associated with the results correspond to the actual locations. Users have the flexibility to adjust these coordinates as needed to ensure accuracy.

Furthermore, the result object is expanded to include a list of non-verified properties. For instance:

    "type": "Feature",
    "properties": {
        "address_line1": "Bürgermeister-Heinrich-Straße 60",
        "address_line2": "93077 Bad Abbach, Germany",
        "housenumber": "60",
        "nonVerifiedParts": [

This extended result object provides transparency by clearly indicating which address components are non-verified, allowing for informed decision-making and customization based on the level of validation required for your specific use case.


This library is open-source and released under the MIT License.

Contributions and Support

We welcome contributions from the developer community. If you encounter any issues or have suggestions for improvements, please feel free to open an issue or submit a pull request on GitHub.

Package Sidebar


Weekly Downloads






Unpacked Size

346 kB

Total Files


Last publish


  • geoapify