Leaflet: Geocoding Geocoding Tutorial

Please note: This tutorial is for our geocoding API, you may instead want our Leafletjs Geosearch Autosuggest tutorial instead.

Install Leaflet Geocoding plugin

Add geocoding control to your webpage

To use the Leaflet plugin, load the plugin's CSS and JavaScript files:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/opencagedata/leaflet-opencage-geocoding@v2.0.0/dist/css/L.Control.OpenCageGeocoding.min.css" />
<script src="https://cdn.jsdelivr.net/gh/opencagedata/leaflet-opencage-geocoding@v2.0.0/dist/js/L.Control.OpenCageGeocoding.min.js"></script>

Then 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',
  limit: 10,
  proximity: '51.52255, -0.10249' // favour results near here
};
var control = L.Control.openCageGeocoding(options).addTo(map);
L.tileLayer('https://tile.thunderforest.com/neighbourhood/{z}/{x}/{y}{r}.png?apikey=YOUR_THUNDERFOREST_API_KEY', {
  attribution: 'Data <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a> contributors, Map tiles &copy; <a href="https://www.thunderforest.com/">Thunderforest</a>',
  minZoom: 4,
  maxZoom: 18
}).addTo(map);

Demo

Note: in this example we use map tiles from our friends at Thunderforest, but you can use any map provider.

Customizing

By default, when a geocoding result is found, the control will center the map on it and place a marker at its location. This can be customized 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 boundingbox when a result is selected.

Options

You can overwrite the following options, for example to translate.
var options = {
    key: 'YOUR-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: {        // additional attributes to add to result
        geohash: 'annotations.geohash',
        what3words: 'annotations.what3words',
        addressComponents: 'components'
    }
};

var control = L.Control.openCageGeocoding(options).addTo(map);

See also

If you prefer to do your frontend development in React please check out react-leaflet-opencage.

Some issues to consider:

Please note that putting your API key in client side javascript means that it is visible to anyone executing that javascript. We recommend you do this only for internal applications.

Please see our detailed guide to protecting your API key(s).

As an added measure of safety subscription customers can define a value for the Access-Control-Allow-Origin header in their account dashboard which will limit AJAX requests to a specific domain. You can find the details in the API documentation.

That being said, one worry that potential clients sometimes raise is that someone will get their key and start using it heavily and they will face a large and unexpected bill. Fear not - that can't happen because of how our pricing works. Subscription customers buy a month in advance, and there is no usage-based charging. If we see an explosion of usage we email you and ask if it is expected and the source is known. If yes, and it will be ongoing, we ask you to move to a higher pricing tier in the future, but this never happens as a surprise. If no, we can help you work out what is going on. Please see all the details of how our pricing works.

Start your free trial

2,500 geocoding API requests per day.

No credit card required.