If you’ve ever built a map-based application, chances are you’ve put a location search box somewhere on it before. And if you’re using our Mapzen Search service, you might not even have to build it yourself!

When we launched Mapzen Search six weeks ago, we knew that there was going to be a number of our users who shared a common need for that search box, so we built a Leaflet geocoder plugin that would get your map working with Mapzen Search very quickly, even if we’ve had to choose some defaults for you.

Of course, we can’t predict or meet everyone’s needs at once. So the plugin is designed so you can customize it beyond the default experience. For instance, you could even direct to another service if you wanted to host your own Pelias-based geocoding service.

And, as a Leaflet plugin, it should provide an abstraction layer over Mapzen Search and Pelias, so if you are already experienced in Leaflet you should not need to learn an entirely different syntax (until you really need to, of course).

So how did we do?

I decided to put our own plugin to the test.

Welcome to the neighbourhood

First, though, let’s get you situated. A basic use of the plugin will drop a search box in the upper-left corner, just like this:

(This map is interactive! Open full screen ➹ )

It’s not really flashy, but it’s not meant to be. It blends right into Leaflet and it does its job.

Dropping it into your project should be straightforward, as well. If you’ve already written some of the code to set up a Leaflet map, there are only a few important lines to add to get started. In an HTML file, load the plugin script and stylesheet somewhere after loading Leaflet:

<!-- in HTML -->
<link rel="stylesheet" href="leaflet-geocoder-mapzen.css">
<script src="leaflet-geocoder-mapzen.js"></script>

Inside of your JavaScript, instantiate your Leaflet map, and then add the geocoder like this.

// In JavaScript
// Get an API key from https://mapzen.com/developers/
L.control.geocoder('<your-api-key>').addTo(map);

And if you need more help getting started, we’ve got your back! We’ve created an in-depth, step-by-step tutorial for the Leaflet geocoder plugin which takes less than 30 minutes to work through. (This was the topic of a Maptime Oakland event in November 2015.)

Remodeling the homestead

Maybe the basic plugin just isn’t enough for you. After all, your project might have a different look and feel, and you want to make that plugin fit your needs, not the other way around.

To understand what some of those needs are, I needed to approach it from another perspective, as a developer with other goals in mind. I decided to start with a small project, the kind of “micro-service” a civic technology-minded person like myself might tackle as a side project or at a series of hack nights.

I was recently inspired to learn more about my own neighborhood’s community board, after attending the Municipal Arts Society (MAS) Summit in New York City, where I now live. I saw how these community boards play a large part in representing neighborhoods and their residents when there are significant projects or policies that impact these communities.

But the city’s own Find Your Community Board page, while informative, didn’t make it as easy as they could have. I was reminded of ANC Finder, a community-built project in Washington, D.C. (where I used to live, also), where you could enter an address and find out which ANC, or Advisory Neighborhood Commission, represented you. These ANCs play a similar role in local politics for DC residents.

So I decided to build a small prototype project that would use the geocoder plugin so New York City residents like myself could easily find out about the community boards that represented us. A few days later, here’s the result.

(This map is interactive! Open full screen ➹ )

Since this was just a prototype, I found myself cutting out a lot of features that I otherwise would have included if this was more of a long-term project. Of course, if you’d like to fork this project or contribute to it, the code is totally open and hosted on GitHub.

But now, I’d like to talk a little bit about what I’ve learned incorporating the plugin on a small project.

Getting to know the neighbours

Fitting the plugin into a different layout was, thankfully, not too difficult. The question I wanted to answer was this: Could I put the search box inside of another box? It did involve manually positioning the search box over another element that existed outside of the map, so it’s not effortless, but it’s doable.

Also, since I could only match up New York City addresses with community board boundaries within the city, I had to structure my search query to be bounded in order to be useful. Since the plugin translated Leaflet syntax into an appropriate query for Mapzen Search behind the scenes, I couldn’t just ask the plugin to filter results by a locality. So I could only pass in a rectangular bounding box containing New York City’s boundaries, but that meant some results from New Jersey could show up in the results. I decided to capture these results by showing the marker anyway but providing a helpful error message.

Another problem showed up in the autocomplete feature. The Mapzen Search API /autocomplete endpoint allows you to boost results around a certain focus point. However, the plugin had never included support for this functionality. For this project, auto-suggested results were coming from all over the world, which gave very confusing feedback for the user. So, for now, I simply turned autocomplete off. This is something we’ll look into adding to the plugin as well.

Lastly, I’ve found that when users perform actions with the plugin, a developer needs to have some hooks so that they can piggy-back on top of (or override!) the search box’s actions. For instance, I wanted to make sure that even though a marker is placed, the default behavior of showing a popup is suppressed. Another case is when a user clears the search result box. For this project, it removed the marker but not the community board boundary or information, which felt strange.

To overcome these problems, I had to overwrite the plugin’s internal methods to make it do what I wanted. This was doable because I was familiar with the guts of the plugin, but none of this is documented behavior, and it could even change without warning in the future! So it’s clear that for these actions, we need to expose and document hooks that developers can use, and make sure that they are covered by tests so that they remain reliable for years to come. Stay tuned for documentation and a blog post on these hooks.

Civic engagement!

Of course, none of these should prevent you from using the Leaflet geocoder plugin in your own projects today if it’s the right fit for you. Some people already are! Map My Story, a project that traces ancestral migration paths that came out ChiHackNight, uses the plugin. So does the Greenpoint-Williamsburg ToxiCity Map, which shows potentially polluted sites in these neighborhoods, and what3emojis, a way to create an address using emoji, and may or may not be a real project (full disclosure: I am an early angel investor of it).

So we hope you find the plugin, and Mapzen Search in general, to be the least painful part of your application development. And if you run into any questions or suggestions for improvement, please let us know! We love hearing from you.

And if you’re a resident of Fort Greene, maybe I’ll see you at a community board meeting sometime!