Getting Started with the Mapbox Geocoding API

What Is Geocoding?

Geocoding converts a human-readable address or place name into geographic coordinates (latitude and longitude). Reverse geocoding does the opposite — it turns a coordinate pair into a human-readable address. Both operations are essential building blocks of location-aware applications.

The Mapbox Geocoding API (now called the Mapbox Search API in its latest form) is one of the most capable and developer-friendly geocoding services available. It supports forward geocoding, reverse geocoding, batch requests, and address autocomplete.

Prerequisites

• A free Mapbox account at mapbox.com
• A public access token from your Mapbox dashboard
• Basic familiarity with HTTP requests and JSON responses

Note on pricing: Mapbox offers a free tier with a generous monthly quota of geocoding requests. Review the current pricing page before deploying to production.

Forward Geocoding

Forward geocoding takes a search text and returns matching locations as a GeoJSON FeatureCollection.

Endpoint

GET https://api.mapbox.com/geocoding/v5/mapbox.places/{search_text}.json
  ?access_token=YOUR_TOKEN
  &limit=5
  &country=us

JavaScript Example

const query = encodeURIComponent('1600 Pennsylvania Ave NW, Washington DC');
const token = 'YOUR_MAPBOX_ACCESS_TOKEN';

const response = await fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json` +
  `?access_token=${token}&limit=1&country=us`
);

const data = await response.json();
const [longitude, latitude] = data.features[0].geometry.coordinates;
console.log(longitude, latitude); // -77.0366, 38.8971

Understanding the Response

The response is a standard GeoJSON FeatureCollection. Each feature in the features array represents a matching place. Key fields to know:

• geometry.coordinates — [longitude, latitude] of the result
• place_name — full human-readable address string
• relevance — score from 0 to 1 indicating match confidence
• place_type — type of place (address, poi, postcode, place, region, country)
• context — array of parent geographies (city, state, country)

Reverse Geocoding

To go from coordinates to an address, pass the longitude and latitude in the search text position:

const lon = -73.9857;
const lat = 40.7484;

const response = await fetch(
  `https://api.mapbox.com/geocoding/v5/mapbox.places/${lon},${lat}.json` +
  `?access_token=${token}&types=address`
);

const data = await response.json();
console.log(data.features[0].place_name);
// e.g., "20 W 34th St, New York, New York 10001, United States"

Use the types parameter to filter results to a specific place type — for example types=address or types=place,region.

Autocomplete / Search-as-You-Type

The Geocoding API supports autocomplete by setting the autocomplete=true parameter (it's enabled by default). To build a responsive search input, debounce your API calls to avoid excessive requests:

let debounceTimer;

searchInput.addEventListener('input', (e) => {
  clearTimeout(debounceTimer);
  debounceTimer = setTimeout(async () => {
    const query = encodeURIComponent(e.target.value);
    if (query.length < 3) return;

    const res = await fetch(
      `https://api.mapbox.com/geocoding/v5/mapbox.places/${query}.json` +
      `?access_token=${token}&autocomplete=true&limit=5`
    );
    const data = await res.json();
    renderSuggestions(data.features);
  }, 300); // wait 300ms after user stops typing
});

Useful Query Parameters

Parameter	Description	Example
limit	Max number of results (1–10)	limit=5
country	Filter by ISO country code(s)	country=gb,fr
types	Filter by place type	types=address,poi
proximity	Bias results near a location	proximity=-73.99,40.73
bbox	Restrict results to a bounding box	bbox=-80,25,-60,45
language	Response language (IETF tag)	language=fr
autocomplete	Enable partial match suggestions	autocomplete=true

Alternatives to Consider

• Nominatim (OpenStreetMap): Free, open-source geocoder with no API key required for low-volume use. Less accurate in some regions.
• Photon: Open-source geocoder backed by OpenStreetMap data, suitable for self-hosting.
• Google Geocoding API: High accuracy globally, especially for business POIs, but pricing is higher at scale.
• HERE Geocoding API: Strong commercial option with a generous free tier.

Best Practices

• Always store your access token in an environment variable — never hardcode it in client-side code that gets committed to a public repository.
• Use the proximity parameter to bias results toward the user's current location for more relevant suggestions.
• Cache geocoding results where possible to reduce API calls and improve perceived performance.
• Handle the case where features is empty — not every query will return a result.