@geoapify/geocoder-autocomplete
Advanced tools
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.
DIV elements), allowing for flexible integration and styling.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:
Install the Geocoder Autocomplete package with NPM or Yarn project manager:
npm install @geoapify/geocoder-autocomplete
# or
yarn add @geoapify/geocoder-autocomplete
Refer to the Geocoder Autocomplete library as a UMD module (for CMS websites, including WordPress):
<html>
<head>
<script src=".../index.min.js"></script>
<link rel="stylesheet" type="text/css" href=".../minimal.css">
...
</head>
...
</html>
You can use UNPKG to refer or download the library:
https://unpkg.com/@geoapify/geocoder-autocomplete@^1/dist/index.min.js
https://unpkg.com/@geoapify/geocoder-autocomplete@^1/styles/minimal.css
@geoapify/geocoder-autocomplete in your projectFollow the steps below to seamlessly integrate @geoapify/geocoder-autocomplete into your project.
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;
}
import { GeocoderAutocomplete } from '@geoapify/geocoder-autocomplete';
const autocomplete = new GeocoderAutocomplete(
document.getElementById("autocomplete"),
'YOUR_API_KEY',
{ /* Geocoder options */ });
autocomplete.on('select', (location) => {
// check selected location here
});
autocomplete.on('suggestions', (suggestions) => {
// process suggestions here
});
autocomplete when you added it as a script:const autocompleteInput = new autocomplete.GeocoderAutocomplete(
document.getElementById("autocomplete"),
'YOUR_API_KEY',
{ /* Geocoder options */ });
autocompleteInput.on('select', (location) => {
// check selected location here
});
autocompleteInput.on('suggestions', (suggestions) => {
// process suggestions here
});
We provide several Themes within the library:
minimal and round-borders - for webpages with light background colorminimal-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">
skipDetails with addDetailsWhen 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(<HTMLElement> el, <String> geoapifyApiKey, <GeocoderAutocompleteOptions> 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});
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. |
The library offers a flexible API that enables the dynamic configuration of Geoapify Geocoder options at runtime:
const autocomplete = new GeocoderAutocomplete(...);
// set location type
autocomplete.setType(options.type);
// set results language
autocomplete.setLang(options.lang);
// set dropdown elements limit
autocomplete.setLimit(options.limit);
// set filter
autocomplete.addFilterByCountry(codes);
autocomplete.addFilterByCircle(filterByCircle);
autocomplete.addFilterByRect(filterByRect);
autocomplete.addFilterByPlace(placeId);
autocomplete.clearFilters()
// set bias
autocomplete.addBiasByCountry(codes);
autocomplete.addBiasByCircle(biasByCircle);
autocomplete.addBiasByRect(biasByRect);
autocomplete.addBiasByProximity(biasByProximity);
autocomplete.clearBias();
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
autocomplete.isOpen();
autocomplete.open();
autocomplete.close();
You have the ability to retrieve the current value or modify the displayed value:
autocomplete.setValue(value);
const displayValue = autocomplete.getValue();
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:
// add preprocess hook
autocomplete.setPreprocessHook((value: string) => {
// return augmented value here
return `${value} ${someAdditionalInfo}`
});
// remove the hook
autocomplete.setPreprocessHook(null);
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.setPostprocessHook(null);
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 {
processedStreets.push(feature.properties.street);
return true;
}
});
return filtered;
});
// remove the filter
autocomplete.setSuggestionsFilter(null);
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) => {
resolve({
"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) => {
resolve({
"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.
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
autocomplete.off('open');
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:
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. |
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.
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": [
"housenumber"
]
},
...
}
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.
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.
FAQs
Postal address autocomplete input field
The npm package @geoapify/geocoder-autocomplete receives a total of 2,891 weekly downloads. As such, @geoapify/geocoder-autocomplete popularity was classified as popular.
We found that @geoapify/geocoder-autocomplete demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.