DEV Community: Erwin Soekianto

Understanding the `near` Parameter in Mapbox's Search Box API

Erwin Soekianto — Fri, 07 Aug 2026 15:31:17 +0000

AI assistants and conversational search are changing how users search for places. Instead of typing an address or dropping a pin, users increasingly ask questions like "Find coffee near the Eiffel Tower" or "Harold Chicken Shack in Chicago." The new near parameter in the Mapbox Search Box API — introduced alongside the new Mapbox Places API (announced July 27, 2026) — makes these natural-language searches easier to implement, by removing the need for a separate geocoding request before you can search.

In this post, we'll break down what near does, why it exists, and how it stacks up against the other location-narrowing parameters Search Box already offers: proximity and bbox.

The problem `near` solves

Traditionally, if you wanted to search for "Harold Chicken Shack" close to Chicago using the /forward endpoint, you had two separate jobs to do:

Put the search term in q — e.g. q=Harold Chicken Shack
Tell the API where to look using proximity or bbox — which meant you needed actual coordinates or a bounding box, not just the word "Chicago"

That works fine for map UIs where you already know the user's location or have a pin on a map. But it breaks down for AI-driven or chat-style search, where a user might just type or say "Harold Chicken Shack in Chicago" — a name and a place, mixed together in plain English, with no coordinate pair in sight. That's the gap near closes.

How `near` works

near accepts either a place-name string (like Chicago, or a broader anchor like California) or an explicit coordinate pair — whichever you have on hand — alongside your search term in q.

near is a convenience layer. When you pass a place name, it first resolves that name via the geocoder's own /forward, then automatically applies the result to your Search Box query. If you pass coordinates directly, near skips the geocoding step and applies them the same way.

The resolution follows a defined hierarchy based on how coarse or fine the anchor is:

`near` value	Resolves to	Effect on `q`
Raw `lon,lat`	Parsed directly	Proximity point
Country (e.g. `United States`)	Geocoded to a country	Bounding box + country filter
Region / state (e.g. `California`)	Geocoded to a region	Bounding box
Place / locality (e.g. `Chicago`)	Geocoded to a place	Proximity point
Neighborhood / address / POI (e.g. `Eiffel Tower`)	Geocoded to a fine feature	Proximity point

In other words: countries and regions/states constrain results by bbox; everything finer than that (cities, neighborhoods, addresses, landmarks) biases results by proximity — which is why a strongly relevant result just outside the anchor can still appear (this is intentional and desirable). Country-level anchors get one thing regions don't: on top of the bbox, near also applies the dedicated country parameter (an ISO 3166-1 alpha-2 code, like US).

One more mechanical detail worth knowing: if you pass both near and proximity in the same request, near takes precedence — it overrides proximity, and promotes whatever proximity value you'd set to origin instead.

Worth noting: passing something coarser, like near=California, is broad enough to constrain results with a bbox instead of just biasing them. Which behavior you get depends on how specific or coarse the anchor is, per the table above.

Here's what that manual, two-step process actually looks like without near — first geocoding "Chicago" via Geocoding v6 /forward, then passing the resulting coordinates into Search Box as proximity:

# Step 1: geocode "Chicago" to get coordinates
https://api.mapbox.com/search/geocode/v6/forward?q=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN
# → returns coordinates around -87.6298,41.8781

# Step 2: pass those coordinates into Search Box as proximity
https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&proximity=-87.6298,41.8781&access_token=YOUR_MAPBOX_ACCESS_TOKEN

With near, both of those become a single request:

https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&near=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN

Same result, one less network round trip.

This is also the connective tissue between Search Box and the new Places API. The typical flow now looks like:

Send a Search Box /forward query that includes near
Get back a mapbox_id
Feed that ID into the Places API's Details endpoint to pull the full enriched record (hours, photos, busyness, attributes, etc.)

One more thing worth knowing: near isn't limited to /forward — it's also supported on /suggest and /category with identical resolution semantics (it's not available on /retrieve or /reverse). So this same pattern applies whether you're building autocomplete, one-shot search, or category browse.

Where this fits in a real product

It's worth being explicit about something the API itself doesn't tell you: near doesn't do any natural-language parsing. It only resolves a location string (or coordinates) that's already been isolated — it doesn't pull "Harold Chicken Shack" and "Chicago" apart out of a single sentence for you. That separation has to happen before you ever call the Search Box API, and whose job that is depends on where your input is coming from:

Structured UI — a traditional search box with a separate location field, a map pin, a "search near me" button, a saved address. Here you already have the two pieces separately (no parsing needed) — you just pass them straight into q and near as-is.
Conversational or AI-driven input — a chatbot, voice assistant, or LLM-powered search bar where the user hands you one freeform sentence. Here, something upstream of your Search Box call — an LLM prompt, an NLU/intent-extraction step, or simpler pattern matching for known formats — has to do the decomposition shown below. near doesn't replace that step; it's the thing you call after it, so you're not also manually geocoding the location piece yourself.

Splitting a natural-language query into `q` and `near`

If the input you're working with is a single fused string — the kind an AI assistant or chat interface might hand you, like "Loyola University Chicago, Chicago, IL, USA" — you'll need to decompose it yourself before calling the API. The rule of thumb: put the specific entity (the POI, brand, or category) in q, and put the administrative tail (the part that only disambiguates where — city, state, country) in near.

Original string	`q`	`near`
`Black Hills National Forest, SD, USA`	`Black Hills National Forest`	`SD, USA`
`Mount Hood, Oregon, USA`	`Mount Hood`	`Oregon, USA`
`coffee in Portland Oregon`	`coffee`	`Portland Oregon`

The same decomposition applies on /suggest (with a partial query in q as the user types). On /category there's no q to decompose at all — the category lives in the path, and near carries the location intent on its own.

`near` vs. `proximity` vs. `bbox`

Search Box already gave you several ways to make a search location-aware. Here's how near fits alongside them.

`proximity` — bias, don't restrict

proximity doesn't filter anything out. It biases ranking so that results closer to a given point are favored, while still allowing results further away to appear. You supply it separately from your query, either as:

ip (use the requester's IP-based location), or
explicit longitude,latitude coordinates

The key distinction: proximity needs you to already have coordinates. It says "rank things near this point," where this point is something your app already knows (user's GPS location, map center, etc.).

`bbox` — a hard rectangular filter

bbox is a strict inclusion filter. Anything outside the box (min_lon,min_lat,max_lon,max_lat) is excluded outright — it's not a ranking signal, it's a wall. Useful when you know a user is restricted to, say, a specific metro area or map viewport and you never want results from outside it.

`near` — resolves to proximity or bbox, depending on the anchor

near accepts a place name or coordinates and resolves them internally into either a proximity bias or a bbox filter, depending on how coarse the anchor is: countries and regions/states constrain by bbox, while places, neighborhoods, addresses, and POIs bias by proximity. Either way, near is saving you the manual geocoding lookup you'd otherwise need before calling proximity or bbox directly — and if you pass both near and proximity together, near wins, with the old proximity value shifted to origin.

A sample request and response

Here's a real request/response pair, tested directly against the live API:

https://api.mapbox.com/search/searchbox/v1/forward?q=Harold%20Chicken%20Shack&near=Chicago&access_token=YOUR_MAPBOX_ACCESS_TOKEN

The (trimmed) response came back as a standard GeoJSON FeatureCollection:

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.84130128, 41.86461828], "type": "Point" },
      "properties": {
        "name": "Harold's Chicken Shack",
        "mapbox_id": "dXJuOm1ieHBvaToxMjI1MjBkMi02MzIyLTQzYjItYmUwMi00MzJhNjBiYzM3ZmU",
        "feature_type": "poi",
        "full_address": "713 Roosevelt Rd, Maywood, Illinois 60153, United States",
        "place_formatted": "Maywood, Illinois 60153, United States",
        "poi_category": ["american restaurant", "food and drink"],
        "metadata": {
          "phone": "+17083566048"
        },
        "distance": 2688893
      }
    },
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.56676837, 41.76573045], "type": "Point" },
      "properties": {
        "name": "Harold's Chicken Shack",
        "full_address": "7114 S Yates Blvd, Chicago, Illinois 60649, United States",
        "place_formatted": "Chicago, Illinois 60649, United States",
        "distance": 2709632
      }
    },
    {
      "type": "Feature",
      "geometry": { "coordinates": [-87.62617297, 41.87392112], "type": "Point" },
      "properties": {
        "name": "Harolds Chicken Shack",
        "full_address": "612 S Wabash Ave, Chicago, Illinois 60605, United States",
        "place_formatted": "Chicago, Illinois 60605, United States",
        "brand": ["Chicken Shack"],
        "brand_id": ["chicken_shack"],
        "distance": 2706643
      }
    }
  ],
  "attribution": "© 2026 Mapbox and its suppliers. All rights reserved."
}

(For reference: distance is reported in meters — 2,688,893 m ≈ 1,671 mi, 2,709,632 m ≈ 1,684 mi, and 2,706,643 m ≈ 1,682 mi.)

All three full results came back within the Chicago metro area. near=Chicago narrowed the search exactly as you'd want it to, with no out-of-area results.

Even without an outlier to compare against, the distance field is still worth flagging: despite all five results being genuinely local to Chicago, distance came back around 2.69–2.71 million meters (roughly 1,671–1,684 miles) for every result. That's consistent with distance being based on proximity/IP-derived location rather than on near — in this case, the default reference point is apparently nowhere near Chicago either. Don't read distance as a signal for how well near narrowed things — check place_formatted/context instead.

Worth calling out too: metadata here is richer than the base parameter reference currently documents. In practice it can include phone, website, and a full open_hours.periods array broken down by day of week — more than the generic "additional metadata" description in the docs suggests. From here, you'd grab mapbox_id and pass it straight to the Places API's Details endpoint for the even fuller enriched record.

Quick comparison

Parameter	What it does	Input format	Filters or just biases?	Best for
`proximity`	Ranks closer results higher	`ip` or `longitude,latitude`	Biases only	Map-based apps that already know user location
`bbox`	Restricts results to an area	`minLon,minLat,maxLon,maxLat`	Hard filter	Viewport-limited or region-locked search
`near`	Resolves a place name or coordinates, then applies them as `proximity` (specific anchors) or `bbox` (coarse anchors)	`string` (place name) or coordinates, paired with `q`	Both — biases for specific anchors, filters for coarse ones	Conversational or natural-language search where you don't want to run a separate geocoding call

When to reach for which

Building a classic search box on a map where you already have coordinates ready for proximity or bbox? Those parameters take coordinates directly. near also accepts coordinates and resolves them the same way, so either path works if that's what you have on hand.
Need a hard boundary, like restricting to a delivery zone or map viewport? Use bbox directly for full control, though a coarse near value (like a country or state) can behave similarly.
Have a search term and a place name — from a chat interface, voice input, or freeform text — and don't want to run a separate geocoding call yourself? That's what near is built for.

For point-like anchors, near produces the same ranking behavior as proximity directly — it's a convenience layer, not a separate ranking engine. For coarse anchors, it can behave like bbox instead. Either way, near isn't computing something proximity/bbox couldn't already do on their own — it's resolving the anchor and choosing the right mechanism for you.

What to expect at the edges

A few error and fallback behaviors worth knowing before you ship this:

Situation	Response
`near` omitted or empty	Falls back to a normal `q` search with no anchor — still valid
`near` set to invalid coordinates	`400 Bad Request`
`near` text isn't geocodable	Graceful fallback — anchor is left unchanged, `q` still runs
Geocoder temporarily unavailable	`500 Internal Server Error`

It's also worth setting expectations on result quality: in internal testing across categories like national forests, universities, airports, and malls, most near-anchored queries resolved to the correct region with the intended entity ranked at or near the top — misses were the exception rather than the rule. The residual misses tend to be ranking order (the right result shows up a few slots down) or narrow indexing gaps — not incorrect anchoring.

Wrapping up

near gives you a single parameter that resolves a place name or coordinates into either a proximity bias or a bbox filter, depending on how specific the anchor is — sparing you a separate geocoding call when all you have is a name or a rough location. It's available on /forward, /suggest, and /category, so this pattern isn't limited to a single query style. bbox and proximity remain the direct, explicit tools for when you already know exactly which behavior you want.

Ready to try it? near is available today in the Search Box API — check the live API reference for the latest parameter details, or test it directly against the /forward, /suggest, and /category endpoints with your own queries. You can also try it in the Search Box Playground.

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

Understanding the `near` Parameter in Mapbox's Search Box API

The problem near solves

How near works

Where this fits in a real product

Splitting a natural-language query into q and near

near vs. proximity vs. bbox

proximity — bias, don't restrict

bbox — a hard rectangular filter

near — resolves to proximity or bbox, depending on the anchor

A sample request and response

Quick comparison

When to reach for which

What to expect at the edges

Wrapping up

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

The problem `near` solves

How `near` works

Splitting a natural-language query into `q` and `near`

`near` vs. `proximity` vs. `bbox`

`proximity` — bias, don't restrict

`bbox` — a hard rectangular filter

`near` — resolves to proximity or bbox, depending on the anchor

Filtering with `types`