A JavaScript library that lets you quickly add a search box and help your users find locations
To get started you need:
- A container to inject the autosuggest into
- An OpenCage geosearch key (available when you become a geosearch customer)
- To specify the domain for the
access-control-allow-originHTTP header (commonly known as a CORS header) in your OpenCage account dashboard
This library comes as a plugin on Algolia's Autocomplete, then, that creates an input and provides the interactivity and accessibility attributes.
By configuring the two required parameters (container and key), and configuring the CORS header in your OpenCage dashboard you can have an interactive geosearch experience for places (countries, states/provinces, cities/towns/villages, suburbs/neighbourhoods, major POIS) around the world.
See a configurable, live demo on the OpenCage site, or play with the html/css/js on codepen.
For convenience, this repository is published as multiple packages. For a simple usage, we bundle it with the Algolia's Autocomplete. To get started, with a simple HTML page, you need a container to anchor the geosearch into:
<div id="place"></div>Then, insert your search experience into it by calling the algoliaAutocomplete function, providing :
- The container (a CSS selector)
- The OpenCage Geosearch API
key
Make sure to provide a container (e.g., a div), not an input. The Geosearch generates a fully accessible search box.
Please note: a geosearch key is unrelated to the keys for the OpenCage geocoding API. Geosearch keys are of the form oc_gs_... and will need to be configured for a specific domain in your OpenCage account dashboard.
<script type="text/javascript">
opencage.algoliaAutocomplete({
container: '#place',
plugins: [
opencage.OpenCageGeoSearchPlugin({
key: 'YOUR-GEOSEARCH-KEY',
}),
],
});
</script>and to run it, just add the following resources to the header of the HTML page:
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle/dist/css/autocomplete-theme-classic.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@opencage/geosearch-bundle"></script>In addition to the mandatory key parameter, the following optional parameters may also be set
bounds- restricts the possible results to a defined bounding box.
The value of the bounds parameter should be specified as two coordinate points forming the south-west and north-east corners of a bounding box (min longitude, min latitude, max longitude, max latitude).
Example usage:
bounds: '-0.563160,51.280430,0.278970,51.683979'
Values that are not valid coordinates are ignored. We have built a small, map-based tool to easily see bounds values.
countrycode- restricts results to the specified country/territory.
The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States.
Example usage:
countrycode: 'de'
Non-two letter country codes are ignored.
language- language to display results in.
A two letter language code (such as es for Spanish or de for German), or native in which case we will attempt to return the response in the local language.
Currently supported languages are: de, en, es, fr.
Example usage:
language: 'de'
If no language is explicitly specified, we default to English en.
We hope to add more languages in the future. Please get in touch if lack of a certain language is preventing you from becoming a customer.
limit- maximum number of results the autosuggest should display.
Default is 5. Maximum allowable value is 10.
Example usage:
limit: 3
debounce- sets the time (in ms) to pass without any typing before doing a request to the API.
Default is 300.
Example usage:
debounce: 250
noResults- sets the label to display when the API returns no results (it is i18n).
Default is No results..
Example usage:
noResults: 'Pas de résultat.'
onActive- callback function called whenever a result is active.
By default, this is an empty function.
Function parameter type:
(params:
{ state: AutocompleteState,
...setters,
event: Event,
item: TItem,
itemInputValue: string,
itemUrl: string,
source: AutocompleteSource }
) => voidonSelect- callback function called whenever a result is selected.
By default, this is an empty function.
Function parameter type:
(params:
{ state: AutocompleteState,
...setters,
event: Event,
item: TItem,
itemInputValue: string,
itemUrl: string,
source: AutocompleteSource }
) => void`| defaults to`({ setIsOpen }) => setIsOpen(false)onSubmit- callback function called when submitting the form.
By default, this is an empty function.
Function parameter type:
(params:
{ state: AutocompleteState,
event: Event,
...setters }
) => voidCheck Algolia's Autocomplete CSS styles
For those who just want a simple HTML / JS integration
This package bumdles the Algolia Autocomplete and our GeoSearch plugin.
For whom is using a javascript dependency manager
This is the core package: the GeoSearch plugin to use with Algolia Autocomplete.
This is a plugin for the well-known map API leaflet. See our integration tutorial.
This is a plugin for the well-known map API OpenLayers. See our integration tutorial.
This project is written with the latest technologies in mind. Thereby it is required to include a polyfill when you wish to support older browsers:
- unfetch, for fetch requests.
Please refer to the following developer's notes
Find a bug or want to request a new feature? Please let us know by submitting an issue.
Geosearch is an entirely different service than geocoding. OpenCage also operates a forward and reverse geocoding API, please don't confuse the geosearch service with the geocoding API.
Learn more about the difference between geosearch and geocoding.
Licensed under the MIT License
A copy of the license is available in the repository's LICENSE file.
We run the OpenCage Geocoding API. Learn more about us.
We also run Geomob, a series of regular meetups for location based service creators, where we do our best to highlight geoinnovation. If you like geo stuff, you will probably enjoy the Geomob podcast.