Search
The public, non-interactive surface of the Search Box API: text search,
reverse lookup, category search, and the category list. suggest and
retrieve/{id} aren't exposed — both need a caller-managed session_token
for a client-side autocomplete flow this CLI has no one-shot equivalent of.
Every command also takes the common flags — --username/-u,
--token/-t, --profile, --id — described in
Shared parameters.
search reverse and geocoder reverse
take the same coordinates and answer different questions: geocoder
returns canonical addresses and administrative hierarchy (country, region,
postcode, place), while search returns POIs and businesses with metadata a
geocoder has no field for — rating, price level, hours of operation, brand.
mapbox search forward
Forward search for an address or POI by free-form text — the one-off equivalent of typing into a search box and taking the first screen of results, with no autocomplete session behind it.
Parameters:
| Parameter | Description |
|---|---|
--q | The search string. Required. Limited to 256 characters. |
--limit | The number of results to return, up to 10. |
--proximity | Bias the response to favor results closer to a specific location. Provide either ip to bias by the caller's IP location, or two comma-separated coordinates in longitude,latitude order. Defaults to IP proximity. |
--near | Bias the response to favor results near a location described by free-form text (a place or city name) or a longitude,latitude pair. Overrides --proximity when resolved. |
--bbox | Limit results to those inside a bounding box, as minLon,minLat,maxLon,maxLat. Cannot cross the 180th meridian. |
--radius | Limit results to those within a radius, in degrees, of the --proximity point. Also provide --proximity when using this. |
--country | A comma-separated list of ISO 3166-1 alpha-2 country codes. |
--types | Limit results to one or more feature types, comma-separated. Omit it and any type may come back. Options include country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi and category. |
--poi-category | Limit results to those in one or more categories, comma-separated. |
--poi-category-exclusions | A comma-separated list of canonical category names to exclude matching POIs. |
--show-closed-pois | Include permanently closed points of interest. Excluded by default. |
--open-now | Limit results to POIs open now, based on hours of operation, if available. |
--minimum-rating | Limit results to those with an average rating of at least this value (0.0-5.0), if rating data is available. |
--price-levels | A comma-separated list of price levels to limit results to, if price data is available. Accepts $, $$, $$$, $$$$. |
--exclude-fields | A comma-separated list of metadata fields to omit from the response, to reduce payload size. Accepts photos, reviews. |
--rank-strategy | Change how results are ranked. Only applies to data sources that support it. Values: distance, relevance. |
--language | The ISO language code to be returned. If not provided, the default is English. |
--auto-complete | Enable Autocomplete Mode, which includes partial and fuzzy matches. |
--sar-type | Search along the path in --route rather than around a point. The only allowed value is isochrone. |
--route | The route to search along, as a polyline-encoded linestring. Requires --sar-type. |
--route-geometry | The precision of --route. Defaults to polyline. Values: polyline, polyline6. |
--time-deviation | Maximum detour from the route, in estimated minutes. |
--eta-type | Enable ETA calculation in the response. The only allowed value is navigation; also requires --navigation-profile and either --origin or --proximity. |
--navigation-profile | When ETA calculation is enabled, the routing profile to use. Values: driving, walking, cycling. |
--origin | When ETA calculation is enabled, the location to calculate distance from, as longitude,latitude. |
Examples:
mapbox search forward --q "34170 Gannon Terrace" --limit 1
mapbox search forward --q coffee --proximity -121.90662,37.42827 --poi-category coffee
mapbox search reverse
Reverse lookup for the addresses and POIs at a coordinate.
Parameters:
| Parameter | Description |
|---|---|
--longitude | The longitude coordinate to search near. Required. |
--latitude | The latitude coordinate to search near. Required. |
--limit | The number of results to return, up to 10. |
--country | A comma-separated list of ISO 3166-1 alpha-2 country codes. |
--types | Limit results to one or more feature types, comma-separated. Omit it and any type may come back. Options include country, region, prefecture, postcode, district, place, city, locality, oaza, block, street, address, poi and category. |
--show-closed-pois | Include permanently closed points of interest. Excluded by default. |
--language | The ISO language code to be returned. If not provided, the default is English. |
Examples:
mapbox search reverse --longitude -118.471383 --latitude 34.023653 --limit 1
mapbox search category
POIs filtered by a canonical category, near a location or route — for
example, all nearby coffee shops for coffee, or all gas stations along a
route for gas_station.
Parameters:
<category> (positional) is the canonical category ID, such as coffee — see
list-category below for the full list. Category search requires one of
--proximity, --near, --bbox or --route, though nothing here enforces
it before the request goes out.
| Parameter | Description |
|---|---|
--proximity | Bias the response to favor results closer to a specific location. Provide either ip or two comma-separated coordinates in longitude,latitude order. |
--near | Bias the response to favor results near a location described by free-form text (a place or city name) or a longitude,latitude pair. |
--bbox | Limit results to those inside a bounding box, as minLon,minLat,maxLon,maxLat. Cannot cross the 180th meridian. |
--radius | Limit results to those within a radius, in degrees, of the --proximity point. Also provide --proximity when using this. |
--limit | The number of results to return, up to 25. |
--country | A comma-separated list of ISO 3166-1 alpha-2 country codes. |
--types | Limit results to one or more feature types, comma-separated. Omit it and any type may come back. Options include country, region, postcode, district, place, city, locality, neighborhood, block, street, address, poi and category. |
--poi-category-exclusions | A comma-separated list of canonical category names to exclude matching POIs. |
--show-closed-pois | Include permanently closed points of interest. Excluded by default. |
--exclude-fields | A comma-separated list of metadata fields to omit from the response, to reduce payload size. Accepts photos, reviews. |
--language | The ISO language code to be returned. If not provided, the default is English. |
--sar-type | Search along the path in --route rather than around a point. The only allowed value is isochrone. |
--route | The route to search along, as a polyline-encoded linestring. Requires --sar-type. |
--route-geometry | The precision of --route. Defaults to polyline. Values: polyline, polyline6. |
--time-deviation | Maximum detour from the route, in estimated minutes. |
--eta-type | Enable ETA calculation in the response. The only allowed value is navigation; also requires --navigation-profile and either --origin or --proximity. |
--navigation-profile | When ETA calculation is enabled, the routing profile to use. Values: driving, walking, cycling. |
--origin | When ETA calculation is enabled, the location to calculate distance from, as longitude,latitude. |
Examples:
mapbox search category coffee --proximity -121.90662,37.42827 --limit 1
mapbox search list-category
The canonical category IDs usable with search category, with a display
name in the requested language. Does not describe parent/child
relationships between categories.
Parameters:
| Parameter | Description |
|---|---|
--language | The ISO language code to be returned. If not provided, the default is English. |
Examples:
mapbox search list-category
mapbox search list-category --language fr