Address geocoding format guide

Forward geocoding converts location text into geographic coordinates, turning 2 Lincoln Memorial Circle NW into -77.050,38.889. Follow these address formatting guidelines to make sure that your Mapbox Geocoding API requests retrieve the right results:

Since secondary address information like apartment or suite numbers does not impact geographic location, the Mapbox geocoder does not use this kind of information to find coordinates. Your query will yield better results if you remove secondary address information, as well as any associated special characters like commas (,) and pound symbols (#).

Examples

• ✅ 123 Main St
• ❌ 123 Main St #456
• ❌ 123 Main St, Suite 7
• ❌ 123 A Main St

Use a single building number rather than a range of numbers when constructing a query.

Examples

• ✅ 123 Main St
• ❌ 123-127 Main St

For addresses in the United States, pass in the address components in the format {house number} {street} {city} {state} {zip}.

For geocoding in countries other than the United States, you have a few options. You can either submit the components in the same order as you would use for an address in the United States, or you can follow local address formatting standards for those countries.

If you need to pick one standard order to use for multiple countries, pass the address components to the geocoder in order from most granular to least granular: {house number} {street} {postcode} {city} {state}.

Examples

• ✅ 123 Main St Boston MA 02111 (US only)
• ✅ 123 Main St Swindon SN2 2DQ (UK only)
• ✅ 123 Main St 02111 Boston MA (multiple countries)

For addresses in the United States, using 5-digit zip codes in searches yields better results than using 9-digit zip codes does.

Examples

• ✅ 02919
• ❌ 02919-3232

If you need to limit results to one country, use the country parameter in the API request instead of including the country in the search text. The country parameter will limit results to only locations within the specified country.

Examples

✅  Results will only include locations within the United States
https://api.mapbox.com/geocoding/v5/mapbox.places/123%20Main%20St%20Boston%20MA.json?country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN

❌ Results could potentially include locations outside of the US
https://api.mapbox.com/geocoding/v5/mapbox.places/123%20Main%20St%20Boston%20MA%20United%20States.json?&access_token=YOUR_MAPBOX_ACCESS_TOKEN`