Episode 1: Geocoding smarter, not harder
This one's about the types parameter on the Mapbox Geocoding API specifically. (The Search Box API has its own types parameter too, but that's a separate product — this post is just about Geocoding.)
Say you're building a signup form and just need the city someone typed. Or you're tagging support tickets by county for routing. Or you just want the state for a sales-tax lookup. You don't need a rooftop-accurate street address — but a lot of geocoders hand you the whole thing anyway, whether you asked for it or not.
Turns out you can filter out the feature types that you don't need — Mapbox lets you ask for exactly the level you need.
TL;DR: the types param filters which feature types come back in the results. Set types=district and you get back only district-type features. (place = city, district ≈ county in the US, region = state, postcode = ZIP).
Filtering with types
Here's a reverse geocode of a point in Manhattan with no types filter — by default this can return separate address, place, region, and country features, all at once:
curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
access_token=TOKEN"
Only need the zipcode for that same point? Filter it down:
curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
types=postcode&
access_token=TOKEN"
Now the features array only contains postcode-type results — something like this:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "dXJuOm1ieHBsYzpBU2VPN0E",
"geometry": {
"type": "Point",
"coordinates": [-74.056834, 40.789203]
},
"properties": {
"mapbox_id": "dXJuOm1ieHBsYzpBU2VPN0E",
"feature_type": "postcode",
"full_address": "Secaucus, New Jersey 07094, United States",
"name": "07094",
"name_preferred": "07094",
"coordinates": {
"longitude": -74.056834,
"latitude": 40.789203
},
"place_formatted": "Secaucus, New Jersey, United States",
"bbox": [-74.094356, 40.75046, -74.033648, 40.807552],
"context": {
"place": {
"mapbox_id": "dXJuOm1ieHBsYzpFYmVvN0E",
"name": "Secaucus",
"wikidata_id": "Q1013249"
},
"district": {
"mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
"name": "Hudson County",
"wikidata_id": "Q490505"
},
"region": {
"mapbox_id": "dXJuOm1ieHBsYzpBbVRz",
"name": "New Jersey",
"wikidata_id": "Q1408",
"region_code": "NJ",
"region_code_full": "US-NJ"
},
"country": {
"mapbox_id": "dXJuOm1ieHBsYzpJdXc",
"name": "United States",
"wikidata_id": "Q30",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"postcode": {
"mapbox_id": "dXJuOm1ieHBsYzpBU2VPN0E",
"name": "07094"
}
}
}
}
],
"attribution": "NOTICE: © 2026 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}
Same idea for county — Mapbox's district type is defined as "smaller than a region, larger than a place," and for US addresses, that maps to a county:
curl "https://api.mapbox.com/search/geocode/v6/reverse?
longitude=-74.05941186207377&
latitude=40.77969220566604&
types=district&
access_token=TOKEN"
Same shape, just at the district level:
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"id": "dXJuOm1ieHBsYzpwQWJz",
"geometry": {
"type": "Point",
"coordinates": [-74.04667, 40.72069]
},
"properties": {
"mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
"feature_type": "district",
"full_address": "Hudson County, New Jersey, United States",
"name": "Hudson County",
"name_preferred": "Hudson County",
"coordinates": {
"longitude": -74.04667,
"latitude": 40.72069
},
"place_formatted": "New Jersey, United States",
"bbox": [-74.166087, 40.641695, -73.98538, 40.823543],
"context": {
"region": {
"mapbox_id": "dXJuOm1ieHBsYzpBbVRz",
"name": "New Jersey",
"wikidata_id": "Q1408",
"region_code": "NJ",
"region_code_full": "US-NJ"
},
"country": {
"mapbox_id": "dXJuOm1ieHBsYzpJdXc",
"name": "United States",
"wikidata_id": "Q30",
"country_code": "US",
"country_code_alpha_3": "USA"
},
"district": {
"mapbox_id": "dXJuOm1ieHBsYzpwQWJz",
"name": "Hudson County",
"wikidata_id": "Q490505"
}
}
}
}
],
"attribution": "NOTICE: © 2026 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained."
}
It works the same way on forward geocoding, and there it also changes which matches come back, not just filters a single result down. The docs' own example: searching q=georgia with no filter can match both the country Georgia and the US state Georgia. Add types=country and only the country comes back — you're excluding a whole category of match, not trimming one result's payload.
You can also stack multiple types in one call, comma-separated — e.g. types=address,street,place to get back any of those three, in one request.
Why it matters
If you're doing this at volume — autocomplete-as-you-type, bulk address cleanup, routing tickets by county — asking for exactly the feature type(s) you need means fewer irrelevant features to filter out client-side, and no risk of grabbing the wrong one out of a mixed results list.
Full list of feature types and how the types param works: Mapbox Geocoding API docs.
Got a favorite obscure API parameter that saved you a bunch of overhead? Drop it in the comments — might be the next episode.
Top comments (0)