OpenCage Geocoding Control for Leaflet

A Leaflet geocoding control that uses OpenCage's geocoding API.

Check out a demo page in /demo. Or take a look at the live demo.

Note: if you want location autosuggest then what you want is OpenCage's geosearch, not geocoding.

Dependencies

Leaflet version 0.7+ to 1.9.x

For Leaflet version 2: check the release branch v3.x

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

npm install leaflet-opencage-geocoding
# or
pnpm add leaflet-opencage-geocoding
# or
yarn add leaflet-opencage-geocoding

The package includes both UMD and ESM builds, which you can import based on your project setup:

// 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:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/opencagedata/[email protected]/dist/css/L.Control.OpenCageGeocoding.min.css"
/>
<script src="https://cdn.jsdelivr.net/gh/opencagedata/[email protected]/dist/js/L.Control.OpenCageGeocoding.min.js"></script>

Other options

• Clone from GitHub: [email protected]:opencagedata/leaflet-opencage-geocoding.git
• Download a zip or tarball archive

Usage

Load the plugin's CSS and JavaScript files:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/opencagedata/[email protected]/dist/css/L.Control.OpenCageGeocoding.min.css" />
<script src="https://cdn.jsdelivr.net/gh/opencagedata/[email protected]/dist/js/L.Control.OpenCageGeocoding.min.js"></script>

Add the plugin's control to an L.Map instance:

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:
    '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> 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:

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.

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. 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.