leaflet-geocoder-mapzen v1.9.4

Leaflet + Mapzen Search geocoding 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.

Demo

See it in action!

Requirements

Requires the Leaflet mapping library. Supports Leaflet v0.7.3 (and higher) and v1.0.0. (Previous Leaflet versions may work, but are not actively tested or supported.)

Browser support is IE8+ (more details below).

To use the Mapzen Search service, you need a Mapzen API key. Get one from the Mapzen developers portal. It's free!

Basic usage

Step 1: In HTML, import the required Leaflet JavaScript and CSS files. Start quickly with hosted libraries on cdnjs!

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

<!-- Load geocoding plugin after Leaflet -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.4/leaflet-geocoder-mapzen.css">
<script src="https://cdnjs.cloudflare.com/ajax/libs/leaflet-geocoder-mapzen/1.9.4/leaflet-geocoder-mapzen.js"></script>

Step 2: In JavaScript, 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: In JavaScript, add your geocoder with your Mapzen API key.

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

Step 4: Rejoice!

There is also a tutorial

It has much more detailed walkthrough instructions and is very friendly for beginners. No coding experience is necessary! Check it out here.

Want this as a module?

Experienced developers can install with npm:

npm install leaflet-geocoder-mapzen

And then import it in your module system. For instance, with Browserify:

// Require Leaflet first
var L = require('leaflet');

// Requiring the plugin extends Leaflet automatically
require('leaflet-geocoder-mapzen');

// You can also store a reference to the geocoder constructor in the require()
var MyGeocoderPlugin = require('leaflet-geocoder-mapzen');

// Now you can do step 2 and 3 from "Basic usage" instructions, above

This plugin implements the Universal Module Definition so you can also use it in AMD and CommonJS environments.

ES2015 (ECMAScript 6)

To import this plugin in ES2015 environments, the import syntax is supported:

import L from 'leaflet';
import 'leaflet-geocoder-mapzen';

// Alternatively
import MyGeocoderPlugin from 'leaflet-geocoder-mapzen';

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 Mapzen Search / Pelias query itself.

Examples

// Searching nearby [50.5, 30.5]
L.control.geocoder('<your-api-key>', {
  focus: [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>', {
  focus: 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);

// Custom filtering and bounding parameters
// For valid parameters, see Mapzen Search documentation for
// search (https://mapzen.com/documentation/search/search/)
// and autocomplete (https://mapzen.com/documentation/search/autocomplete/)
// Note that some parameters use dot notation and so must be quoted
// in JavaScript otherwise it will result in a syntax error
L.control.geocoder('<your-api-key>', {
  params: {
    sources: 'whosonfirst',
    'boundary.country': 'AUS'
  },
  placeholder: 'Results via Who’s on First in Australia'
}).addTo(map);

Interaction behavior

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

Examples

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

// Customizing layer 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);

// Disabling layer icons
L.control.geocoder('<your-api-key>', {
  pointIcon: false,
  polygonIcon: false
}).addTo(map);

// Disable zoom/pan to a point while browsing the results (up/down arrows)
L.control.geocoder('<your-api-key>', {
  panToPoint: false
}).addTo(map);

// Set the geocoder to always be the full width of the map
// By default, the geocoder is only full width when the screen is less than 650 pixels wide
L.control.geocoder('<your-api-key>', {
  fullWidth: true
}).addTo(map);

// Disable markers for search results
L.control.geocoder('<your-api-key>', {
  markers: false
}).addTo(map);

// Force the geocoder to always be in the expanded state
L.control.geocoder('<your-api-key>', {
  expanded: true
}).addTo(map);

// Changing attribution
// By default, adds "Geocoding by Mapzen" 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);

Custom text strings

These are the text strings that are used by the geocoder control. You can override these strings by passing in a textStrings options object containing the names of the string(s) you want to customize. You can use this method to localize the controls for a different language, for instance.

UI text

HTTP status code errors

Learn more about possible error messages in Mapzen Search documentation. ERROR_DEFAULT is a catch-all error that displays when a request returns an error with an unexpected HTTP status code (or none at all) — one example where this can happen is when a browser is prevented from making a request due to a security concern, such as the lack of CORS headers on the search endpoint.

Examples

// Uses custom text strings to localise the geocoder control.
L.control.geocoder('<your-api-key>', {
  textStrings: {
    INPUT_PLACEHOLDER: '도시, 지명 등을 검색해보세요.',
    INPUT_TITLE_ATTRIBUTE: '도시, 지명 등을 검색해보세요.',
    RESET_TITLE_ATTRIBUTE: '다시 검색하기',
    NO_RESULTS: '해당 결과가 없습니다.',
    ERROR_403: '해당 서비스를 사용하기 위해서는 API KEY가 필요합니다.',
    ERROR_404: '검색 서비스를 찾을 수 없습니다. :-(',
    ERROR_408: '검색에 예상보다 긴 시간이 소요되고 있습니다. 조금 있다가 다시 시도해보는 건 어떨까요?',
    ERROR_429: '지나치게 많은 리퀘스트가 발생했습니다. 조금 있다가 다시 시도해보는 건 어떨까요?',
    ERROR_500: '검색 서비스가 현재 작동하지 않고있습니다. 조금 있다가 다시 시도해보는 건 어떨까요?',
    ERROR_502: '네트워크 상태가 불안정합니다. 조금 있다가 다시 시도해보는 건 어떨까요?',
    ERROR_DEFAULT: '검색 서비스에 문제가 있는 것으로 보입니다. :-('
  }
}).addTo(map);

See this in action!

Advanced usage

Examples with running code can be found in the examples directory.

Alternate syntax

You can instantiate 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

When instantiating a geocoder, you may assign it to a variable. This will allow you to use its methods later on.

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

With alternate require() or import syntax

If you require() or import and set it to a variable, you can also use new with that variable.

var MyGeocoderPlugin = require('leaflet-geocoder-mapzen');

// Alternatively
import MyGeocoderPlugin from 'leaflet-geocoder-mapzen';

// Then
var geocoder = new MyGeocoderPlugin('<your-api-key>');

Properties

You can retrieve the current version of the geocoder.

console.log(geocoder.version);

Methods

There are additional methods on the geocoder that you can use.

// Expand the geocoder.
// Fires the `expand` event.
geocoder.expand();

// Collapse the geocoder.
// This works even if the option `expanded` is set to true!
// Fires the `collapse` event.
geocoder.collapse();

// Focus on the geocoder input.
// This will also expand the geocoder if it's collapsed.
geocoder.focus();

// Removes focus from the geocoder input.
// This also clears results and collapses the geocoder (if enabled).
geocoder.blur();

// Clears inputs and results from the geocoder control.
// This does not affect collapse or expanded state, and does not remove focus.
// Fires the `reset` event.
geocoder.reset();

Events

The geocoder includes all of Leaflet's events methods and adds additional events that you can subscribe to, so that you can customize what happens when users interact with the geocoder. When you instantiate a new geocoder, assign it to variable, as above, and then you can use the event methods to listen for the events that it's firing. For example:

geocoder.on('select', function (e) {
  console.log('You’ve selected', e.feature.properties.label);
});

All of Leaflet's event methods are available, such as on, off, once, and so on. The exact syntax and how it behaves are inherited from the version of Leaflet you are plugging into, so there are slight differences between the 0.7.x version line and the 1.0.0 version line.

The following events are fired:

Here is a demo of the events.

Getting data

Certain events will pass data as the first argument to the event listener's callback function.

on results or error

In addition to the base event object from Leaflet, the event object will contain these other useful properties:

If there was an error with the request, the event object will contain the additional properties:

on select and highlight

on focus and blur

Browser support

This plugin supports all Leaflet-supported browsers except for Internet Explorer 7. It 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 requests in JSONP.

Using a Pelias-compatible endpoint

This project was renamed as of v1.3.0 to be more closely associated with Mapzen Search, the hosted geocoding service provided by Mapzen that requires an API key. You can still point the geocoder at a different service running Pelias, Mapzen's open-source geocoder, by changing the url option (see Query behavior, above) to the desired endpoint. If an API key is not required, the parameter may be omitted or be set to undefined or null.

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.

Do you support TypeScript?

Not officially. There are community-supplied type definitions at DefinitelyTyped.

Projects using this plugin

• Map My Story
• Greenpoint-Williamsburg ToxiCity Map
• what3emojis
• NYC Community Boards
• Wantoid

Let us know if you have a project you'd like to share!