https://github.com/opencagedata/leaflet-opencage-geocoding
A Leaflet geocoding control that uses the OpenCage geocoding API
https://github.com/opencagedata/leaflet-opencage-geocoding
geocoder geocoding leaflet opencage opencage-data
Last synced: 2 months ago
JSON representation
A Leaflet geocoding control that uses the OpenCage geocoding API
- Host: GitHub
- URL: https://github.com/opencagedata/leaflet-opencage-geocoding
- Owner: OpenCageData
- License: bsd-2-clause
- Created: 2014-04-17T16:03:40.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2023-01-21T22:11:53.000Z (about 3 years ago)
- Last Synced: 2024-05-02T04:34:29.793Z (almost 2 years ago)
- Topics: geocoder, geocoding, leaflet, opencage, opencage-data
- Language: JavaScript
- Homepage:
- Size: 309 KB
- Stars: 22
- Watchers: 13
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# OpenCage Geocoding Control for Leaflet
A [Leaflet](http://leafletjs.com/) geocoding control that uses OpenCage's [geocoding API](https://opencagedata.com).
Check out a demo page in `/demo`. Or take a look at the live [demo](https://opencagedata.com/tutorials/geocode-in-leaflet).
Note: if you want location autosuggest then what you want is [OpenCage's geosearch](https://opencagedata.com/geosearch), not geocoding.
## Dependencies
Leaflet version 0.7+ to 1.9.x
For Leaflet version 2: check the [release branch v3.x](https://github.com/OpenCageData/leaflet-opencage-geocoding/tree/release/v3.0.0)
## Breaking changes
Starting with version 2.1, Bower is no longer supported. The package is now published on npm in both UMD and ESM formats.
## Installation
### Via npm
```bash
npm install leaflet-opencage-geocoding
```
The package includes both UMD and ESM builds, which you can import based on your project setup:
```javascript
// ESM
import 'leaflet-opencage-geocoding';
// CommonJS
require('leaflet-opencage-geocoding');
```
### Via CDN (for vanilla JS/HTML projects)
For classic HTML projects, you can use the CDN:
```html
```
### Other options
- Clone from GitHub: `git@github.com:opencagedata/leaflet-opencage-geocoding.git`
- Download a [zip or tarball archive](https://github.com/opencagedata/leaflet-opencage-geocoding/tags)
## Usage
Load the plugin's CSS and JavaScript files:
```HTML
```
Add the plugin's control to an `L.Map` instance:
```javascript
var map = L.map('map').setView([51.52255, -0.10249], 13);
var options = {
key: 'your-api-key-here',
limit: 10,
};
var control = L.Control.openCageGeocoding(options).addTo(map);
L.tileLayer('http://tile.osm.org/{z}/{x}/{y}.png', {
attribution:
'© OpenStreetMap contributors',
}).addTo(map);
```
## Customizing
By default, when a geocoding result is found, the control will centre the map on it and place a marker
at its location. This can be customised by overwriting the control's markGeocode function to perform
any action desired.
For example:
```javascript
var control = L.Control.openCageGeocoding(options).addTo(map);
control.markGeocode = function (result) {
var bbox = result.bbox;
L.polygon([
bbox.getSouthEast(),
bbox.getNorthEast(),
bbox.getNorthWest(),
bbox.getSouthWest(),
]).addTo(map);
};
```
This will add a polygon representing the result's bounding box when a result is selected.
## Options
You can overwrite the following options, for example, to translate.
```javascript
var options = {
key: '', // your OpenCage API key
limit: 5 // number of results to be displayed
position: 'topright',
placeholder: 'Search...', // the text in the empty search box
errorMessage: 'Nothing found.',
showResultIcons: false,
collapsed: true,
expand: 'click',
addResultToMap: true, // if a map marker should be added after the user clicks a result
onResultClick: undefined, // callback with result as first parameter
resultExtension: {
geohash: "annotations.geohash",
what3words: "annotations.what3words",
addressComponents: "components"
} //if additional attributes from OpenCage search API should be added to the result
};
var control = L.Control.openCageGeocoding(options).addTo(map);
```
## Contributing
See `CONTRIBUTING.md` file.
## License
See `LICENSE` file.
### Who is OpenCage GmbH?
We run the [OpenCage Geocoder](https://opencagedata.com). Learn more [about us](https://opencagedata.com/about).
We also run [Geomob](https://thegeomob.com), 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](https://thegeomob.com/podcast/).