Did You Know? Mapbox Geocoding API Lets You Filter by Feature Type

Erwin Soekianto — Tue, 14 Jul 2026 17:04:57 +0000

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.

Quick Tip: Dynamic Speed Units in Mapbox Navigation SDK for Android

Erwin Soekianto — Wed, 17 Jun 2026 00:03:21 +0000

Hi everyone! I’m Erwin, the newest Developer Evangelist at Mapbox. As I explore our SDKs, I’m focused on making our samples more flexible and easier to implement.

Today, I’m sharing how to add a real-time MPH/KMH toggle to our Render speed limit for a route sample. This implementation is based on the Localization & internationalization guide in our docs.

The Implementation

In the Mapbox Navigation SDK for Android, the speed units are determined by the unitType passed via DistanceFormatterOptions. To make it dynamic, we cache the last location result to refresh the UI instantly.

You can view the full source code changes for this enhancement in this commit on GitHub.

1. Updating the Layout

First, we add a simple button to our layout to trigger the unit switch.

<androidx.appcompat.widget.AppCompatButton
    android:id="@+id/toggleUnitButton"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Toggle Unit"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintTop_toTopOf="parent" />

2. The Toggle Logic

Rebuild your options and trigger a refresh using the cached LocationMatcherResult:

private var lastLocationMatcherResult: LocationMatcherResult? = null

binding.toggleUnitButton.setOnClickListener {
    val newUnit = if (distanceFormatterOptions.unitType == UnitType.METRIC) 
                    UnitType.IMPERIAL else UnitType.METRIC

    distanceFormatterOptions = distanceFormatterOptions.toBuilder()
        .unitType(newUnit)
        .build()

    // Immediate UI refresh
    lastLocationMatcherResult?.let { updateSpeedLimit(it) }
}

3. Updating the View

Pass the updated options into the MapboxSpeedInfoApi to get the correctly formatted speed "sign" data:

private fun updateSpeedLimit(locationMatcherResult: LocationMatcherResult) {
    val info = speedInfoApi.updatePostedAndCurrentSpeed(
        locationMatcherResult,
        distanceFormatterOptions
    )
    if (info != null) {
        binding.speedLimitView.isVisible = true
        binding.speedLimitView.render(info)
    } else {
        binding.speedLimitView.isVisible = false
    }
}

Why it matters

Localization isn't just a "set and forget" feature. Providing a seamless way to switch units enhances the driving experience for users crossing borders or those with specific personal preferences.
For a deeper dive into localization, check out our full documentation here. Expect more tips as I continue my journey with the Mapbox ecosystem!

DEV Community: Erwin Soekianto

Did You Know? Mapbox Geocoding API Lets You Filter by Feature Type

Filtering with types

Why it matters

Quick Tip: Dynamic Speed Units in Mapbox Navigation SDK for Android

The Implementation

1. Updating the Layout

2. The Toggle Logic

3. Updating the View

Why it matters

Filtering with `types`