Search Products
Mapbox provides a full suite of products and services that enable you to add location-based search to your applications or data projects. These products include front-end search libraries and SDKs for web and mobile applications, as well as web services APIs for integration into any environment.
In this guide, you'll learn about common search UX patterns and the Mapbox search products and services that support them. You'll also find links to documentation, code examples, and API playgrounds to help you get started with location-based search.
Search UX Patterns
Below you can find common user experience patterns related to location-based search that you can implement in your applications using Mapbox products and services.
Interactive Text Search
Interactive text search combined with an interactive map is the most common location search pattern for web and mobile applications. A floating search box allows users to search for points of interest, locations, and addresses. When a search result is selected, the map flies to its location and displays a marker.
Type in the search box to test it out. Results are biased towards New York City.
The demo integrates Mapbox Search JS (powered by the Search Box API) with the Mapbox GL JS library for rendering interactive maps.
Category Search
Category search allows users to search for points of interest (POIs) by category, such as restaurants, hotels, or parks. These are usually connected to the map to search for category matches in the current viewport or near the user's location.
Click a category to see the search results. Results are biased to the center of the map. You can try moving to a different location and searching again.
Coordinate Search (reverse geocoding)
Coordinate search, also known as reverse geocoding, allows users to search for addresses or points of interest by entering coordinates. This is useful for applications that need to display location information based on a user's current location or a selected point on a map.
Drag the marker to a new location to request a Coordinate Search result for nearby points of interest (POIs). The result's name property will be displayed in the panel at the top left of the map.
Address Autocomplete
Address Autocomplete is the auto-filling and validating of address forms in web and mobile apps (also referred to as Address Autofill or Address Form Fill). Address autocomplete is a common feature in e-commerce, delivery, and other applications that require users to enter addresses, and helps prevent errors and improve the user experience.
Try address autofill using a live example in the Mapbox Search JS documentation:
Try address autofill in a simulated online checkout experience.
To get started with address autocomplete, see the guide for your platform:
Learn about address autofill in Mapbox Search JS.
Learn about address form fill in an iOS application.
Learn about address autofill in an Android application.
Frontend search products
Mapbox provides front-end search products for web and mobile applications. These products interact with the Mapbox Search APIs behind the scenes and provide standard user interface components that make it easier to add search functionality to applications with minimal effort.
Mapbox Search JS
Mapbox Search JS is a JavaScript library that provides a search box for use in web applications. The package includes React components as well as web components and is applicable in any web development environment. The search box provides autocomplete suggestions as users type, and displays search results on a map.
To get started with Mapbox Search JS, see its documentation and code examples.
View sample code for adding a search box to a web map using Mapbox Search JS.
Search SDK for Android
The Mapbox Search SDK for Android is a software development kit (SDK) that provides a search box for use in Android applications. The search box provides autocomplete suggestions as users type, and displays search results on a map.
To get started with the Maps SDK for Android, see its documentation and code examples.
Add search UI to a map in an Android application.
Search SDK for iOS
The Search SDK for iOS is a software development kit (SDK) that provides a search box for use in iOS applications. The search box provides autocomplete suggestions as users type, and displays search results on a map.
To get started with the Maps SDK for iOS, see its documentation and code examples.
Add a drop-in search UI to a Mapbox map in an iOS application.
These front-end search products may also include "core" APIs, interfaces that allow you to interact with the search functionality programmatically and bring your own user interface components. See search wrappers section below.
Frontend Search Product Pricing
Pricing for frontend search products is based on usage of the underlying search APIs. See the Search API Pricing section below for more information.
Search APIs
Mapbox has two web services APIs for searching locations and addresses: the Search Box API and the Geocoding API. You can access these APIs from any environment that can make HTTP requests, such as web browsers, mobile applications, and server-side code.
The differences between the Search Box API and the Geocoding API are subtle, but important. The Search Box API includes points of interest (POIs) in its results, while the Geocoding API does not. The Geocoding API also supports both permanent and temporary geocoding requests, batch processing, and structured input.
| Feature | Search Box API | Geocoding API |
|---|---|---|
| Includes Points of Interest (POIs) | ||
| Session-based billing | ||
| Permanent Storage Allowed* | ||
| Batch Processing | ||
| Structured Input |
* Permanent geocoding incurs higher costs than temporary geocoding. See the Mapbox Pricing Page for details.
Search Box API
The Search Box API supports interactive search, category search, forward search, and reverse search. Search Box API responses can include addresses, places, and points of interest (POIs). The typical use case for the Search Box API is to provide search suggestions as users type in a search box, and to retrieve detailed information about a selected search result.
| Search Type | Description |
|---|---|
| Interactive Search | Provides autocomplete search suggestions, intended for use as a user types in a search input. |
| Category Search | Searches for points of interest (POIs) by category. |
| Forward Search | Converts a full search query to a list of matching locations (intended for non-interactive search input) |
| Reverse Search | Converts coordinates to a list of matching locations. |
To get started with the Search Box API, see its reference documentation or explore its API Playgrounds:
Experiment with parameters and see response data for the /suggest and /retrieve endpoints of the Search Box API.
Experiment with parameters and see response data for the /forward and /reverse endpoints of the Search Box API.
Geocoding API
The Geocoding API supports non-interactive geocoding of addresses and reverse geocoding of coordinates. The typical use case for the Geocoding API is to enrich your data with location information (for example, batch geocoding to add point coordinates to a list of addresses), or to power other location-based services.
The Geocoding API does not include points of interest (POIs) in its results. If you need to search for POIs, use the Search Box API instead.
To get started with the Geocoding API, see its reference documentation or try its API Playground:
Experiment with request parameters for the Geocoding API using a graphical interface, and inspect the API response object.
Address Autocomplete
Since address autocomplete is a frontend-specific feature, it is intended to be accessed via the frontend search products listed above and is not available as a separate web API.
Wrapping Libraries
You can use Mapbox Search APIs directly, but you can also use one of several wrapper libraries to integrate them into applications across platforms. These libraries provide a more convenient way to interact with the APIs and may include additional features or functionality.
- Mapbox Search JS - Use
Search JS Coreto interact with both the Search Box API and Geocoding API in a web or node.js environment. - Mapbox Search SDK for iOS - Use the
Search Coremodule for iOS to interact with the Search Box API and Geocoding API in an iOS environment. - Mapbox Search SDK for Android - Use the
Search Coremodule for Android to interact with the Search Box API and Geocoding API in an Android environment.
Other use cases
- Bulk Geocoding - Convert a list of addresses to coordinates in a single HTTP POST request to the Geocoding API.
- Address Validation - Validate user-entered addresses to clean up data and prevent errors.
- GPS Trace Lookup - Use reverse geocoding to convert GPS coordinates from vehicles to human-readable addresses.
- Discover Administrative Boundaries - Reverse geocode coordinates to find the city, state, and country where a user point is located.
Search API Pricing
Pricing for search APIs depends on the product and type of request.
The Search Box API's interactive search (using the suggest and retrieve endpoints) is session-based. A single user making multiple requests in a short period of time is considered a single session. The Search Box API's forward and reverse search endpoints are not session-based, so each request is billed separately.
All Geocoding API requests are billed separately, but temporary versus permanent geocoding requests are priced differently.
For full details, see the Mapbox Pricing page.