Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
September 26, 2020 18:02
September 28, 2020 12:07
September 26, 2020 18:02
September 26, 2020 19:47
July 4, 2019 07:11
September 26, 2020 19:36
November 27, 2017 17:29
November 18, 2017 10:05
September 26, 2020 18:02
January 20, 2021 11:13
June 26, 2015 11:50
September 26, 2020 18:02
July 2, 2019 06:28

OpenLayers Control Geocoder

build status npm version license dependency status devDependency status

A geocoder extension for OpenLayers. Requires OpenLayers v3.11.0 or higher.

geocoder anim


You can see here a demo or on jsFiddle if you prefer. There is also a demo of creating a custom provider


The plugin supports (for now) the following providers:

Custom Providers

You can also write your own provider, passing an instance of it to the Geocoder constructor via the provider property of the options argument.

For an example of defining and using a custom provider see examples/custom-provider.js

Custom providers must implement the following methods:


  • options {Object}
    • query Search string entered by the user;
    • lang {string} Preferable language;
    • limit {number} Limit of results;


  • results {Object} Parsed JSON response from API call

How to use it?


npm install ol-geocoder

CDN Hosted - jsDelivr

Load CSS and Javascript:

<link href="" rel="stylesheet">
<script src=""></script>
CDN Hosted - UNPKG

Load CSS and Javascript:

<link href="" rel="stylesheet">
<script src=""></script>
Self hosted

Download latest release and (obviously) load CSS and Javascript.

Instantiate with some options and add the Control
var geocoder = new Geocoder('nominatim', {
  provider: 'mapquest',
  key: '__some_key__',
  lang: 'pt-BR', //en-US, fr-FR
  placeholder: 'Search for ...',
  targetType: 'text-input',
  limit: 5,
  keepOpen: true
Listen and do something when an address is chosen
geocoder.on('addresschosen', function(evt){
  var feature = evt.feature,
      coord = evt.coordinate,
      address = evt.address;
  // some popup solution
  content.innerHTML = '<p>'+ address.formatted +'</p>';



new Geocoder(type, options)

  • type {String} - Maybe later we will have other types like 'reverse'. So for now just pass 'nominatim'.

  • options is an object with the following possible properties:

    • provider : 'osm' (default), 'mapquest', 'photon', 'pelias', 'bing', 'opencage', custom provider instance; Your preferable provider;
    • key : ''; API Key if required;
    • autoComplete : false; Search as you type;
    • autoCompleteMinLength: 2; The minimum number of characters to trigger search;
    • autoCompleteTimeout : 200; The mimimum number of ms to wait before triggering search if autoComplete is on and minimum number of characters is satisfied;
    • placeholder : 'Search for an address'; Placeholder for text input;
    • targetType : 'glass-button'; Can also be 'text-input';
    • featureStyle :; Feature style;
    • lang : 'en-US'; Preferable language;
    • limit : 5; Limit of results;
    • countrycodes : ''; Only valid for osm and mapquest; Limit search results to a specific country (or a list of countries). This is an [ISO 3166-1alpha2 code] (, e.g. gb for the United Kingdom, br for Brazil, etc;
    • keepOpen : false; Whether the results keep openned;
    • preventDefault : false; Whether panning (and creating marker) when an address is chosen;
    • debug : false; If true logs provider's response;

Instance Methods


Returns the layer {ol.layer.Vector} created by Geocoder control.


Returns the source {ol.source.Vector} created by Geocoder control.


@param {String} provider

Sets a new provider.


@param {String} key

Sets provider key.


Triggered when an address is chosen
geocoder.on('addresschosen', function(evt) {
  // it's up to you;