Geocoding - Web Quickstart

Mapbox Geocoding provides a convenient way to leverage the Mapbox Geocoding API in a web or Node environment. Create interactive, powerful search sessions enabling users to search for address and places.

Easy-to-use UI components can be dropped into websites as standalone elements or as part of a comprehensive map experience.

This Quickstart Guide will help you get started with Geocoding using the Mapbox Search JS Web framework (using HTML Custom Elements).

To use Geocoding in a React app, see the Geocoding React Quickstart.

Prerequisites

To use Mapbox Search JS, you need to have a Mapbox access token.

Your default public token

You can use your default public token to get started with the code snippets in this guide.

To get your default public token, login to account.mapbox.com and scroll down to the Access Tokens section.

This access token associates your search requests with a Mapbox account for billing. For more information on creating and using access tokens, see our token management documentation.

Installation

There are two ways to include Mapbox Search JS depending on your web project's architecture. You can use the Mapbox CDN to quickly add Mapbox Search JS to any web page with a <script> tag. For more complex projects that use a javascript module bundler such as webpack or rollup, you can install Mapbox Search JS via npm.

Installation when using the Mapbox CDN

Include the Mapbox Search JS Web framework in your project by adding the following <script> tag to the <head> in your HTML file.


<script id="search-js" defer src="https://api.mapbox.com/search-js/v1.0.0-beta.24/web.js"></script>

This script will give you access to Mapbox's HTML Custom Elements (<mapbox-address-autofill>,<mapbox-search-box> <mapbox-geocoder>, etc ) as well as the mapboxsearch global object. These will allow your webpage access to the Mapbox Search JS functionality.

Installation when using a Module Bundler

Install the NPM package.


npm install --save @mapbox/search-js-web

There is no default export for @mapbox/search-js-web, you must use named exports.


import { MapboxAddressAutofill, MapboxSearchBox, MapboxGeocoder, config } from '@mapbox/search-js-web'

Using the Custom Element in HTML

You can add the <mapbox-geocoder> component directly to your HTML, wherever you would like the geocoder's interactive input to appear. This method does not require JavaScript code after adding the library to your project.


<div>
  <mapbox-geocoder
    access-token="YOUR_MAPBOX_ACCESS_TOKEN"
    proximity="0,0"
  >
  </mapbox-geocoder>
</div>

This will implement the geocoder UI, but additional JavaScript is necessary to handle the response when a user chooses a suggested search item.. You can query the document to get the MapboxGeocoder instance, then set its properties or add an event listener to handle the response when a user selects an item from the list.


<script>
  const script = document.getElementById('search-js');
  // wait for the Mapbox Search JS script to load before using it
  script.onload = function () {
    // select the MapboxGeocoder instance
    const geocoder = document.querySelector('mapbox-geocoder')

    // set the options property
    geocoder.options = {
      language: 'es',
      country: 'MX'
    }

    // add an event listener to handle the `retrieve` event
    geocoder.addEventListener('retrieve', (e) => {
        const feature = e.detail;
        console.log(feature) // geojson object representing the selected item
    });
  }
</script>

Using the Custom Element in JavaScript

You may also add the <mapbox-geocoder> element to the page after it loads via JavaScript code by using the MapboxGeocoder class. You can configure its behavior by setting various properties on the element's instance before adding it to the DOM.

This method may be preferable for users who are already using a lot of JavaScript in their projects, and want to control and configure geocoder from their JavaScript code.

Implementation when using the Mapbox CDN


// add an empty div to append the geocoder to
<div></div>

<script>
  const script = document.getElementById('search-js');
  // wait for the Mapbox Search JS script to load before using it
  script.onload = function () {
      // instantiate a <mapbox-geocoder> element using the MapboxGeocoder class
      const geocoderElement = new mapboxsearch.MapboxGeocoder()

      geocoderElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

      // set the options property
      geocoderElement.options = {
        language: 'es',
        country: 'MX'
      }

      // append <mapbox-geocoder> to the document
      document.querySelector('div').appendChild(geocoderElement);
  };
</script>

Implementation when using a module bundler


import { MapboxGeocoder } from '@mapbox/search-js-web'

// instantiate a <mapbox-geocoder> element using the MapboxGeocoder class
const geocoderElement = new MapboxGeocoder()

geocoderElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set the options property
geocoderElement.options = {
  language: 'es',
  country: 'MX'
}

// append <mapbox-geocoder> to the document
document.querySelector('div').appendChild(geocoderElement);

Integration with a Mapbox GL JS Map

The <mapbox-geocoder> custom element can be used in a standalone fashion, but a common use case is to zoom to a location on a map and show a marker pin after the user chooses a result. <mapbox-geocoder> includes convenient configuration options for binding with a Mapbox GL JS Map instance to achieve this functionality.

The bindMap() method binds to the Map instance, and the settings mapboxgl and marker are used to create the Marker.


<link href="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.4.0/mapbox-gl.js"></script>

...
<div id='geocoder-container'></div>
<div id="map" style="height: 400px; width: 400px"></div>

<script>
  const script = document.getElementById('search-js');
  // wait for the Mapbox Search JS script to load before using it
  script.onload = function () {
    const mapboxAccessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';

    // instantiate a map
    const map = new mapboxgl.Map({
        accessToken: mapboxAccessToken,
        container: 'map',
        center: [-74.5, 40],
        zoom: 9
    });

    // instantiate a geocoder
    const geocoder = new mapboxsearch.MapboxGeocoder()

    // set the mapbox access token, geocoding API options
    geocoder.accessToken = mapboxAccessToken
    geocoder.options = {
      language: 'es'
    }

    // set the mapboxgl library to use for markers and enable the marker functionality
    geocoder.mapboxgl = mapboxgl
    geocoder.marker = true

    // bind the geocoder instance to the map instance
    geocoder.bindMap(map)

    // add the geocoder instance to the DOM
    document.getElementById('geocoder-container').appendChild(geocoder)
  }
</script>