Skip to main content

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 Mapbox Search JS Web.

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.5.0/web.js"></script>

This script will give you access to Mapbox Search JS Web classes (MapboxAddressAutofill,MapboxSearchBox MapboxGeocoder, etc ) as well as the mapboxsearch global object.

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 MapboxGeocoder​

MapboxGeocoder is a JavaScript class. Instantiating it produces a DOM element you can append anywhere in your document, or pass to a Mapbox GL JS map via map.addControl().

To use MapboxGeocoder instantiate the class, add your access token (required), configure it with the available parameters (optional) and append it to the DOM.

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

// instantiate a new MapboxGeocoder
const geocoderElement = new MapboxGeocoder()

geocoderElement.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN'

// set options for language, country, and proximity
geocoderElement.options = {
  language: 'es',
  country: 'MX',
  proximity: [-99.1332, 19.4326]
}

// append to the DOM - (adjust as necessary for your document)
document.querySelector('div').appendChild(geocoderElement);

Integration with a Mapbox GL JS Map​

MapboxGeocoder 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. MapboxGeocoder includes convenient configuration options for binding with a Mapbox GL JS Map instance to achieve this functionality.

import mapboxgl from 'mapbox-gl'
import { MapboxGeocoder } from '@mapbox/search-js-web'
import 'mapbox-gl/dist/mapbox-gl.css'

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 new geocoder instance
const geocoder = new MapboxGeocoder()

// set the mapbox access token and geocoding API options
geocoder.accessToken = mapboxAccessToken
geocoder.options = {
  language: 'es',
  proximity: [-74.5, 40]
}

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

// add the geocoder instance to the Map Control interface
map.addControl(geocoder)
EXAMPLE
Add Geocoder to a Web Map

Try out a working example showing the MapboxGeocoder bound to a Mapbox GL JS map.

Working with events​

While MapboxGeocoder works seamlessly when implemented with a Mapbox GL JS map, there are many cases when you will want to add in additional functionality to the geocoder or trigger other code on MapboxGeocoder interactions. MapboxGeocoder provides many events which allow you to listen to and extend functionality. See the API Reference for a full list.

Below is an example of a retrieve event which logs the selected suggestion.

const geocoder = new MapboxGeocoder();
...

// 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
});

Additional Resources​

Quickstart Guides are also available for the other main features of Mapbox Search JS:

Geocoding can also be implemented with a custom UI by using the Mapbox Search JS Core Framework.

Was this page helpful?