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

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:

1. Put the search term in q — e.g. q=Harold Chicken Shack
2. 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:

1. Send a Search Box /forward query that includes near
2. Get back a mapbox_id
3. 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": "[phone]"
        },
        "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.