Tutorials and hands-on lessons for learning

Find Locations with Filters

Create a mobile-friendly resource locator with custom filters

View fullscreen demo

Locating resources doesn’t always mean figuring out how to get from point A to point B. When trying to answer the question ‘what is nearby?’, users are also looking to narrow down choices by services or amenities available at each location.

Our ‘Finder’ Impact Tool is a template code based on our Store Locator tutorial with the addition of filter options and mobile-friendly design. Use it to create a resource finder application using a spreadsheet of locations. Customize a few fields in the code to match it to your data fields and make it your own.

Getting started

There are a few resources you'll need to get started:


Tools we'll use:

  • Text Editor (Atom, VSCode, JSFiddle) to write and edit your code.‍
  • Mapbox account to access: ‍‍‍

    Mapbox Studio to create your map style.

    Mapbox GL JS to add interactivity to your map and publish it on the web‍‍.

  • csv2geojson to convert CSV and TSV files to GeoJSON data suitable for maps‍
  • GitHub account to publish your Mapbox GL JS map

Set up your CSV

Set up a CSV with the data for your map. Start with a copy of this template or start your own. The example data was sourced from Seattle Open Data.

The CSV will need the following:

  1. Longitude and latitude fields
  2. Filterable fields (fields you want to use to filter your data)

Longitude and latitude fields:

Each location needs latitude and longitude coordinates to appear as a marker on your map. Name, Address, and additional fields can be displayed on the sidebar and within popups. The field names are Latitude and Longitude and not Lat or Long or another abbreviation.

Need help with generating lat/long points? You can use Nominatim, an open-source OpenStreetMap tool, for forward and reverse geocoding.

  • Go to https://nominatim.openstreetmap.org/
  • Search an address in the search bar
  • Click the Details button, copy the coordinates listed in the Center Point row, and paste into your spreadsheet.

Filterable fields:

Each filter that you want to create should have its own column in the spreadsheet. Within a column, each input option must be separated by a comma. The columns Languages, Devices_available, and Clients are all examples of filterable fields. Notice how in the sample spreadsheet, there is a column for Languages and each row within that column contains language options - with multiple options separated by a comma.

Filters and column headers are case sensitive, so be sure that input values are uniform. For example, if we initialize the filter for ‘Monday’ then entries inputted as ‘monday’ or ‘Mon’ would not be affected. Additionally, entries missing a comma such as ‘Monday Tuesday’, would not be removed with the filters ‘Monday’ or ‘Tuesday’.

Copy the template code

Download the template from the GitHub repository. Unzip the folder. In the 'finder-template' folder, you will see 4 files:

  • config.js: This is the file you will be working in.
  • index.html: This contains the HTML and some CSS styling rules from Assembly.css for the template. You can open this file in your browser to see your progress as you edit your code - or use a local server option like the ‘Go Live’ function in VSCode.
  • app.js: This contains the code for the template.
  • style.css: This file has additional styling rules for the application.

Configure the template

Set up your app by making some small edits to the config.js file, using in your text editor.

Choose a Mapbox style

Mapbox Light is included in the template by default. To use a different base map from Mapbox core styles or your own custom style, swap in the style URL of your choice.

style: 'mapbox://styles/mapbox/light-v10',

Add your Mapbox credentials

Without an access token, the rest of the code will not work.‍

Login or create a free Mapbox account. Find your access token on your Access tokens page or the main page you sign into your Mapbox account.

Note: We recommend using the URL restriction feature on the token to avoid token misuse and want to emphasize that only public tokens should be posted to public repositories. Find out more information about how to securely manage your access tokens.

Copy and paste your access token into the code, here:

 accessToken: "pk.eyJ1IjoibWFwYm94LWNvbW11bml0eSIsImEiOiJja2tkN21jcjAwMG51MnBxdHAxemdueGpzIn0.e0IzLkytGq4pcGGieP8KNA",;

Add your CSV

Link your data spreadsheet. If you are using a CSV file, add that file to your template folder. Then connect it to your config.js file by replacing the “./example.csv” with the path and file name of your CSV file ( for example, “./MyLocations.csv”). If you used a Google Sheet to publish your CSV, follow the instructions outlined in the Sheet Mapper tutorial to configure the link and paste that link to assign it to the CSV property. (Remember to edit the ‘Share’ settings on your Sheet.)

 CSV = './Sample_Data.csv',

Center the map

By default, the map is centered on Washington and is set to Zoom 6. Update where the map is centered by replacing the longitude and latitude coordinates with new coordinates and adjusting the zoom level.

Mapbox provides maps in 23 zoom levels, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in).

    center: [-120.234, 47.398], // [lng, lat]
    zoom: 6, // zoom extent

Add a title and description

Consider how much space your text will take up on the screen. Note that because of the mobile-friendly design of this template, the description text will not be visible on small screens, if using the default template code.

    title: 'Replace with your title',
    description: 'Replace with information about your application.',

Change sidebar listing information

Add information about each location to the sidebar. Replace the sidebar property placeholders ‘Location_Name’, ‘Address’, and ‘Phone’ with your data column names. If you would like to add information from more columns to the sidebar, add each 'new field' in quotes and separate them with commas.

    sideBarInfo: ["Location_Name", "Address", "Phone"],

Add popups

Whenever a user clicks on the sidebar or on an individual location displayed on your map, a popup corresponding to that field in your data will be displayed. To populate your popup with information, under popupInfor, replace the default ‘Location_Name’ with the name of the column from your data that contains the information that you would like to display (e.g. ‘Location_Name’ or ‘Address’).

    popupInfo: ["Location_Name"],

Add filters

Time to add some custom filters! This application accepts two different types of filters: drop down or checkbox. You can add as many filters to the template as you want, but for ease of use we recommend limiting the number of filters to 2-3. By default, the application displays 3 filters.

To initialize a dropdown filter, first set the type to dropdown. Next, add a title for your filter. In the example data, the titles for the drop downs are “Languages supported: " and "Clients: ".

Add the name of the field containing the filterable values to columnHeader. Lastly, add the filterable values to the list of options, being careful to put the values in quotes and separate them by commas. Each value should be in quotes and separated by a comma. For example, if we wanted to filter by days of the week the listItems entries would be :

listItems: [‘Monday’, ‘Tuesday’, ‘Wednesday’, ‘Thursday’, ‘Friday’ ]

    type: "dropdown",
    title: "Languages supported: ",
    columnHeader: "Languages",
    listItems: [
        "Language Line Services",

Checkbox filters

To initialize a checkbox filter, first set the type to checkbox. Next, add a title for your filter. In the example, the title is “Devices available: ".

Add the name of the field containing the filterable values to columnHeader. Lastly, add the filterable values to the list of options, being careful to put the values in quotes and separate them by commas. Each value should be in quotes and separated by a comma. For example, if we wanted the filters to match the example above, the listItems entries would be:

listItems: [‘Phone’, ‘Wi-Fi’, ‘Adaptive Laptops’]

    type: "checkbox",
    title: "Devices available: ",
    columnHeader: "Devices_available", // Case sensitive - must match spreadsheet entry
    listItems: ["Computer", "Wi-Fi", "Adaptive Laptops"] // Case sensitive - must match spreadsheet entry; This will take up to six inputs but is best used with a maximum of three;

Publish your map

You’ve made a web map! But it isn’t a webpage yet… to do that we need some way to host a webpage. There are many different ways to host a webpage. Read this guide to learn how to publish your finished map on GitHub, Netlify, or Glitch.

Finished project

View our finished example map at https://labs.mapbox.com/impact-tools/finder/.

Need more help? Ask questions on Stack Overflow or contact Mapbox Support. If you are working on a social good project, contact the Mapbox Community Team.

Want to share what you’ve built? Tweet it with #builtwithmapbox

Was this page helpful?