Address geocoding format guide
Forward geocoding converts location text into geographic coordinates, turning 2 Lincoln Memorial Circle NW into -77.050,38.889. A basic Geocoding API request with an address looks like:
https://api.mapbox.com/search/geocode/v6/forward?q=2%20Lincoln%20Memorial%20Cir%20NW&access_token=YOUR_MAPBOX_ACCESS_TOKEN
Use the following address formatting guidelines to make sure that your Mapbox Geocoding API requests retrieve the right results.
Encode the address correctly
The search text must be expressed as a URL-encoded UTF-8 string. The address cannot contain the semicolon character ; (either raw or URL-encoded).
- ✅
2%20Lincoln%20Memorial%20Cir%20NW - ❌
2 Lincoln Memorial Circle NW
Unencoded, the address must be 20 words and numbers or fewer, separated by spacing and punctuation. The unencoded address can be 256 characters at most.
Use one building number, not a number range
Use a single building number rather than a range of numbers when constructing a query.
- ✅
123 Main St - ❌
123-127 Main St
Format address components consistently
Addresses in the United States
For addresses in the United States, pass in the address components in the format {house number} {street} {city} {state} {zip}.
- ✅
123 Main St Boston MA 02111(US)
Addresses outside the United States
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 ({house number} {street} {city} {state} {zip}), or you can follow local address formatting standards for those countries.
- ✅
123 Main St Swindon SN2 2DQ(UK) - ✅
Fraunhoferstraße 6 80469 München Bavaria(Germany)
Addresses in multiple 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}.
- ✅
123 Main St 02111 Boston MA(multiple countries)
Use the country parameter
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.
✅ Results will only include locations within the United States
https://api.mapbox.com/search/geocode/v6/forward?q=123%20Main%20St%20Boston%20MA&country=US&access_token=YOUR_MAPBOX_ACCESS_TOKEN
❌ Results could potentially include locations outside of the US
https://api.mapbox.com/search/geocode/v6/forward?q=123%20Main%20St%20Boston%20MA%20United%20States&&access_token=YOUR_MAPBOX_ACCESS_TOKEN`
Zip code formatting
For addresses in the United States, you can use either the five- or the nine-digit zip code. Both zip code formats will return the same coordinate results when used in a forward geocoding query.
- ✅
02919 - ✅
02919-3232
Secondary address information
If the types parameter is not defined or includes secondary_address, searching for secondary addresses will be enabled.
Secondary address queries are detected after a "designator" token (for example "Apt", "Suite", "Unit", "#") is followed by an identifier token (for example "12B", "A", "103").
When a parent address has known secondary addresses, the Geocoding API will first return any units that match the provided identifier. If there is no match for the identifier, the API will return the unit exactly as typed, using the same coordinates as the parent address. n
- ✅
123 Main St - ✅
123 Main St #456 - ✅
123 Main St, Suite 7 - ✅
123 Main St, Building A