# 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](https://docs.mapbox.com/ja/cli/reference/#shared-parameters).

`search reverse` and [`geocoder reverse`](https://docs.mapbox.com/ja/cli/reference/geocoder/#mapbox-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`](#mapbox-search-forward)
-   [`mapbox search reverse`](#mapbox-search-reverse)
-   [`mapbox search category`](#mapbox-search-category)
-   [`mapbox search list-category`](#mapbox-search-list-category)

## `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:**

```sh
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:**

```sh
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:**

```sh
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:**

```sh
mapbox search list-category
mapbox search list-category --language fr
```