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.21/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>
Try out a working example showing the <mapbox-geocoder> HTML custom element bound to a Mapbox GL JS map.
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.