Introducing Natural Language Queries in the Mapbox Search Box API

Today, we’re introducing Natural Language Queries in the Mapbox Search Box API in public preview. Mapbox Search already powers thousands of applications, helping people find the right place by name, category, or location. This launch enables  queries to now include  more natural, multi-part searches. This means users can search the way they naturally speak – combining places, categories, locations, amenities, and operating hours – and get relevant POI results in a single query.

People don’t always search for one thing at a time. They might ask for “dog-friendly brunch spots with outdoor seating” or “coffee shops with wifi that are open now near me.” Until now, supporting searches like these required developers to build custom query parsing, make separate calls to resolve location, or add a Large Language Model (LLM) in front of a search API, increasing latency, cost, and complexity.

The new Natural Language Queries eliminate this effort and complexity by absorbing it into the Search Box API. Now, the Search Box API  can understand combinations of places, categories, locations, amenities, and operating hours, and return accurate, ranked POI results in a single API call. This gives developers a simple and fast way to build natural search experiences, especially for their AI applications and agents.

Search should understand the full question

People are increasingly asking complete questions instead of typing short search terms and sequentially filtering each subsequent set of results. When searching for places,, the location itself is often only one part of what they want to find.

Consider a few examples:

• “Pizza in Chicago”
• “Starbucks in Seattle”
• “Dog friendly brunch spots with outdoor seating in the Mission”
• “Wheelchair accessible restaurants with accessible parking near Union Square”
• “Coffee shops with wifi that are open now near me”

Each query combines multiple conditions. A useful search result needs to understand the type of place, the geographic reference, and the supported attributes the user cares about.

Traditional keyword search can struggle when all of those signals appear in one query. An application might find a place with the right name in the wrong city, overlook an amenity request, or require the user to break the search into several smaller steps.

Natural Language Queries are designed to understand those signals together, so people can search more naturally and developers can spend less time building query-processing logic around their search experience.

How Mapbox Natural Language Queries work

The new Natural Language support adds query understanding directly to the Mapbox Search Box API.

On /forward, Mapbox identifies supported parts of a natural-language query, such as a place name, brand, address, location, amenity, or operating hours, then resolves the geographic context and searches Mapbox place data using those conditions. 

One request can contain several intents

“Blue Lagoon in Iceland” contains a place name and a location. “Pizza in Chicago” combines a category and a city. “Coffee shops with wifi that are open now near me” combines a category, an amenity, operating hours, and proximity.

Natural Language Queries are built to recognize these combinations as one request instead of treating the full text as one undifferentiated string. For developers, that means end-user input can be passed through with less client-side processing.

It works with existing Search Box API patterns

Natural Language Queries are applied automatically on /forward. Request and response formats remain the same.

The capability is not applied to /suggest or /retrieve. Those endpoints are designed for autocomplete, where the user is still typing and the full meaning of the request may not be available yet. For applications that need complete natural-language place requests, /forward is the better fit.

Why not put an LLM in front of a search API?

Large language models can read a sentence and identify its parts. But parsing the sentence is only one part of place search.

The application still needs to resolve a city, neighborhood, address, or landmark to a location. It then needs to search the place database and apply supported attributes such as wifi, accessibility, or operating hours.

Teams can build this pipeline themselves, but it often means more requests, more code, additional model cost, and more latency.

Natural Language Queries move common query understanding into the Search Box API. Developers can send the search as typed and receive ranked place results from one Search Box request.

For teams already using an LLM, this can also reduce prompt logic for common place searches. The language model can focus on the broader conversation while Mapbox handles place resolution and retrieval.

What developers can build with natural-language place search

Find places using everyday language

A local discovery or productivity app could accept:

“quiet coffee shops with wifi where I can work, open now near me”

Instead of asking the user to search for coffee first and then apply several filters, the application can pass the full request to Search Box API.

Combine accessibility needs with location

An application could support: “wheelchair accessible restaurants with accessible parking near Union Square”

This combines the place category, accessibility-related attributes, and a landmark-level geographic reference in one request.

Understand neighborhoods and local context

A dining app could accept: “dog friendly brunch spots with outdoor seating in the Mission”

The Search Box API can interpret the category and attributes while resolving “the Mission” as the geographic area for the search.

Support travel and driving use cases

Travel and automotive applications often receive searches that mix a place with a city, state, or region. Examples such as “Black Hills National Forest SD ” or “museums near Salt Lake City” can be resolved without a separate location parsing step before the place search.

Give AI assistants map-ready place results

AI assistants and agents often need to turn a place mentioned in a conversation into coordinates or a ranked place result.

Natural Language Queries let developers pass that place request to the Search Box API without first building a separate intent-extraction layer for common place-search patterns. That makes Mapbox Search useful as the place retrieval layer behind AI-powered applications, grounded in structured location and place data.

Get started with Mapbox Natural Language Queries

There is no separate feature switch.

If your application uses /forward, multi-part query understanding is applied automatically. Standard Search Box pricing applies, and requests are billed the same whether the query contains one intent or several. Free monthly credits also apply.

A request can be as simple as:

GET /search/searchbox/v1/forward?q=restaurants with outdoor seating and is wheelchair friendly in seattle 
&access_token={token}

Start with familiar place searches, then test combinations that match how people use your product: place plus city, category plus neighborhood, brand plus location, or category plus supported amenities and hours. Explore the Search Box API playground. 

Summary

People search for places in complete thoughts, not database fields.

Natural Language Queries in the Mapbox Search Box API make it easier for applications to understand those searches as written. Developers can handle combinations of place names, categories, locations, amenities, and hours in a single Search Box request, without building a separate parsing pipeline for common cases.

The result is simpler development and a search experience that feels much closer to the way people naturally ask for places.

Frequently asked questions

What kinds of queries are supported for Natural Language Queries?

Natural Language Queries are designed for searches that combine supported place-search intents, including place name plus address, place name plus location, category plus location, brand plus location, category plus proximity, and category plus supported amenities or hours.

Examples include “The Louvre Museum, Paris”, “Starbucks in Seattle,” and “coffee shops with wifi that are open now near me.”

What kinds of queries are not the best fit?

The feature is focused on place retrieval, not open-ended conversational reasoning. It works best when the request can be connected to supported place types, geographic references, and structured Mapbox place attributes. Read the documentation  

Very subjective requests, unsupported attributes, or long questions that require broader reasoning outside place search may still need application logic or an AI model. Partial text entered during autocomplete should continue to use /suggest and /retrieve.

Do I need to change my existing integration?

If you already use /forward, no new response schema or separate setup is required. Natural Language Queries are applied automatically on that endpoint.

Applications built around /suggest and /retrieve will not receive multi-part query handling through those autocomplete endpoints.

Can I still use Mapbox Natural Language Queries with an LLM or AI agent?

Yes. Natural Language Queries can sit behind an AI assistant or agent as the place-search layer. The assistant can pass a place request to Search Box API and receive structured, map-ready results without having to perform common location parsing itself.

How is Mapbox Natural Language Queries priced?

Natural Language Queries are included in standard Search Box pricing. There is no separate charge for a request just because it contains several intents, and existing free monthly credits apply.