Leaflet geocoder plugin

A plugin that adds the ability to search (geocode) a Leaflet-powered map using Mapzen Search or your own hosted version of the Pelias Geocoder API.

Requirements

Supports Leaflet v0.7.3 (and higher) and v1.0.0-beta.1. (Previous Leaflet versions may work, but these are not targeted.)

Demo

Click here

Basic usage

Step 1: Import the required Leaflet JavaScript and CSS files

<!-- Load Leaflet from CDN -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.5/leaflet.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.5/leaflet.js"></script>

<!-- Load Pelias geocoding plugin after Leaflet -->
<link rel="stylesheet" href="pelias-leaflet-geocoder.css">
<script src="pelias-leaflet-geocoder.js"></script>

Step 2: Initialize your Leaflet map

// This is an example of Leaflet usage; you should modify this for your needs.
var map = L.map('map').setView([40.7259, -73.9805], 12);
L.tileLayer('http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

Step 3: Add a custom geocoder

Get a Mapzen Search API key from the Mapzen developers portal. It's free!

L.control.geocoder('<your-api-key>').addTo(map);

Step 4: Rejoice!

Browser support

The Pelias-Leaflet geocoder supports all Leaflet-supported browsers except for Internet Explorer 7. The plugin makes a cross-domain request in Javascript to obtain search results, which is not supported in IE7 without JSONP. Mapzen Search does not support API requets in JSONP.

Customizing the plugin

You can optionally specify additional settings to the plugin by passing in an object as a second argument to the geocoder() method, like so:

var options = {
  bounds: true,
  position: 'topright',
  expanded: true
}

L.control.geocoder('<your-api-key>', options).addTo(map);

Here are a list all the settings and their default values.

Query behavior

Some options affect the Pelias query itself.

option	description	default value
url	String. Host endpoint for a Pelias-compatible search API.	`'https://search.mapzen.com/v1'`
bounds	Leaflet LatLngBounds object or Boolean. If `true`, search is bounded by the current map view. You may also provide a custom bounding box in form of a LatLngBounds object.	`false`
latlng	Leaflet LatLng object or Boolean. If `true`, search is biased to prioritize results near the center of the current view. You may also provide a custom LatLng value (in any of the accepted Leaflet formats) to act as the center bias.	`false`
layers	String or Array. Layers to query (see documentation for more details). If not provided, results will come from all available layers. NOTE: layers is not available for the autocomplete query.	`null`

Interaction behavior

These options affect the plugin's appearance and interaction behavior.

option	description	default value
position	String. Corner in which to place the geocoder control. Values correspond to Leaflet control positions.	`'topleft'`
attribution	String. Attribution text to include for Pelias. Set to blank or `null` to disable.	`'Geocoding by <a href=\'https://mapzen.com/pelias\'>Pelias</a>'`
placeholder	String. Placeholder text to display in the search input box. Set to blank or `null` to disable.	`'Search'`
title	String. Tooltip text to display on the search icon. Set to blank or `null` to disable.	`'Search'`
panToPoint	Boolean. If `true`, selecting a search result pans the map to that location.	`true`
pointIcon	String. Path to the image used to indicate a point result. Set to a falsy value to disable.	`'images/point_icon.png'`
polygonIcon	String. Path to the image used to indicate a polygon result. Set to a falsy value to disable.	`'images/polygon_icon.png'`
markers	Leaflet Marker options object or Boolean. If `true`, search results drops Leaflet's default blue markers onto the map. You may customize this marker's appearance and behavior using Leaflet marker options.	`true`
fullWidth	Integer or Boolean. If `true`, the input box will expand to take up the full width of the map container. If an integer breakpoint is provided, the full width applies only if the map container width is below this breakpoint.	`650`
expanded	Boolean. If `true`, the search input is always expanded. It does not collapse into a button-only state.	`false`
autocomplete	Boolean. If `true`, suggested results are fetched on each keystroke. If `false`, this is disabled and users must obtain results by pressing the Enter key after typing in their query.	`true`

Examples

// Different position
L.control.geocoder('<your-api-key>', {
  position: 'topright'
}).addTo(map);

// Searching nearby [50.5, 30.5]
L.control.geocoder('<your-api-key>', {
  latlng: [50.5, 30.5], // this can also written as {lat: 50.5, lon: 30.5} or L.latLng(50.5, 30.5)
  placeholder: 'Search nearby [50.5, 30.5]'
}).addTo(map);

// Taking just the center of the map (lat/lon) into account
L.control.geocoder('<your-api-key>', {
  latlng: true,
  placeholder: 'Search nearby'
}).addTo(map);

// Searching within a bounding box
var southWest = L.latLng(40.712, -74.227);
var northEast = L.latLng(40.774, -74.125);
var bounds = L.latLngBounds(southWest, northEast);

L.control.geocoder('<your-api-key>', {
  bounds: bounds,
  placeholder: 'Search within ' + bounds.toBBoxString()
}).addTo(map);

// Taking just the bounding box of the map view into account
L.control.geocoder('<your-api-key>', {
  bounds: true,
  placeholder: 'Search within the bounds'
}).addTo(map);

// Coarse Geocoder: search only admin layers
L.control.geocoder('<your-api-key>', {
  layers: 'coarse',
  placeholder: 'Coarse geocoder'
}).addTo(map);

// Address Geocoder: search only (street) address layers
L.control.geocoder('<your-api-key>', {
  layers: 'address',
  placeholder: 'Address geocoder'
}).addTo(map);

// POI Geocoder: search only points of interests
L.control.geocoder('<your-api-key>', {
  layers: 'venue',
  placeholder: 'Venues geocoder'
}).addTo(map);

// Street level Geocoder: search only venue and street addresses
L.control.geocoder('<your-api-key>', {
  layers: ['venue', 'address'],
  placeholder: 'Street Geocoder'
}).addTo(map);

// Customizing icons
L.control.geocoder('<your-api-key>', {
  pointIcon: 'http://www.somewhereontheweb.com/download/img/point.png',
  polygonIcon: 'https://cloud.com/polygon-icon.svg'
}).addTo(map);

// Configure if you want to zoom/pan to a point while browsing the results (up/down arrows)
// panToPoint set to true (by default)
// as per https://github.com/pelias/leaflet-geocoder/issues/6
L.control.geocoder('<your-api-key>', {
  panToPoint: true
}).addTo(map);

// Setting full width on the search text box
// by default: 650 (pixels)
L.control.geocoder('<your-api-key>', {
  fullWidth: true
}).addTo(map);

// Configure if you want to drop a pin for a search results or not
// by default - this is set to true
// as per https://github.com/pelias/leaflet-geocoder/issues/7
L.control.geocoder('<your-api-key>', {
  markers: false
}).addTo(map);

// Ability to collapse to a button instead of a expanded text box
// by default - this is set to false
// as per https://github.com/pelias/leaflet-geocoder/issues/7
L.control.geocoder('<your-api-key>', {
  expanded: false
}).addTo(map);

// Changing attribution
// By default, adds "Geocoding by Pelias" text with a link
// You can remove this if you like, or change the text.
L.control.geocoder('<your-api-key>', {
  attribution: null
}).addTo(map);

Advanced usage

Alternate syntax

You can initialize a geocoder with the new keyword. Notice that the class names are capitalized. This is what actually happens under the hood of L.control.geocoder(), so this syntax does not do anything different, but you may prefer it for clarity or stylistic reasons.

new L.Control.Geocoder('<your-api-key>').addTo(map);

Scripting with the plugin

After initializing a geocoder you may store an instance of the geocoder object to a variable.

var geocoder = L.control.geocoder('<your-api-key>');

// or with `new` keyword
var geocoder = new L.Control.Geocoder('<your-api-key>');

// later
geocoder.addTo(map);

The plugin extends Leaflet's Control class, so you may use any of those methods to modify plugin behavior in your script.

// examples
geocoder.setPosition('topright');
var element = geocoder.getContainer();
geocoder.removeFrom(map); // or geocoder.remove() in Leaflet v1

Accessing other plugin internals

Properties and methods used internally by the geocoder are also available on the returned object. These are purposefully not private or obscured, but they are also not publicly documented right now, since functionality may fluctuate without notice. Depending on usage and demand we will lock down and document internal properties and methods for general use. Please let us know in the issues tracker if you have feedback.

rmglennon/leaflet-geocoder