# Geocoder

Converts between place names and coordinates, forward and reverse. Every command also takes the common flags — `--username`/`-u`, `--token`/`-t`, `--profile`, `--id` — described in [Shared parameters](https://docs.mapbox.com/cli/reference/#shared-parameters).

-   [`mapbox geocoder forward`](#mapbox-geocoder-forward)
-   [`mapbox geocoder reverse`](#mapbox-geocoder-reverse)
-   [`mapbox geocoder batch`](#mapbox-geocoder-batch)

## `mapbox geocoder forward`

Looks up a location from search text; returns its standardized address, context, and coordinates.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `--q` | The feature you're trying to look up. This could be an address, a city name, etc. The search text should be expressed as a URL-encoded UTF-8 string, and must not contain the semicolon character (either raw or URL-encoded). Your search text, once decoded, must consist of at most 20 words and numbers separated by spacing and punctuation, and at most 256 characters. |
| `--address-line1` | Structured input: A string including address_number and street. These values can also be provided as separate parameters `address_number` and `street`. |
| `--address-number` | Structured input: The number associated with the house. |
| `--street` | Structured input: The name of the street in the address. |
| `--block` | Structured input: In some countries like Japan, the block is a component in the address. |
| `--place` | Structured input: Typically these are cities, villages, municipalities, etc. They're usually features used in postal addressing, and are suitable for display in ambient end-user applications where current-location context is needed (for example, in weather displays). |
| `--region` | Structured input: Top-level sub-national administrative features, such as states in the United States or provinces in Canada or China. |
| `--postcode` | Structured input: Postal codes used in country-specific national addressing systems. |
| `--locality` | Structured input: Official sub-city features present in countries where such an additional administrative layer is used in postal addressing. Examples include city districts in Brazil and Chile and arrondissements in France. |
| `--neighborhood` | Structured input: Colloquial sub-city features often referred to in local parlance. Not available for reverse geocoding requests. |
| `--permanent` | Specify whether you intend to store the results of the query (`true`) or not (`false`, default). Permanent geocoding allows caching and storing results indefinitely. Requires a valid credit card on file or an active enterprise contract. |
| `--autocomplete` | Specify whether to return autocomplete results (`true`, default) or not (`false`). When autocomplete is enabled, results will be included that start with the requested string, rather than responses that match it exactly. For example, a query for `India` might return both `India` and `Indiana` with autocomplete enabled, but only `India` if it's disabled. |
| `--bbox` | Limit results to only those contained within the supplied bounding box. Bounding boxes should be supplied as four numbers separated by commas, in `minLon,minLat,maxLon,maxLat` order. The bounding box cannot cross the 180th meridian. You can use the [Location Helper](https://labs.mapbox.com/location-helper/) to find a bounding box. |
| `--country` | Limit results to one or more countries. Permitted values are [ISO 3166 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes separated by commas. |
| `--format` | Specify the desired response format of results (`geojson`, default) or for backwards compatibility (`v5`). Values: `geojson`, `v5`. |
| `--language` | Set the language of the text supplied in responses. Also affects result scoring, with results matching the user's query in the requested language being preferred over results that match in another language. For example, an autocomplete query for things that start with `Frank` might return `Frankfurt` as the first result with an English (`en`) language parameter, but `Frankreich` ("France") with a German (`de`) language parameter. |
| `--limit` | Specify the maximum number of results to return. The default is `5` and the maximum supported is `10`. |
| `--proximity` | Bias the response to favor results that are closer to this location. Provided as two comma-separated coordinates in `longitude,latitude` order, or the string `ip` to bias based on reverse IP lookup. |
| `--types` | Filter results to include only a subset (one or more) of the available feature types. Options are `country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `street`, and `address`. Multiple options can be comma-separated. Values: `country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `street`, `block`, `address`, `secondary_address`. |
| `--worldview` | Returns features that are defined differently by audiences that belong to various regional, cultural, or political groups. If `worldview` is not set, the `us` worldview boundaries are returned by default. Values: `ar`, `cn`, `in`, `jp`, `ma`, `rs`, `ru`, `tr`, `us`. |
| `--entrances` | Specify whether to return building entrance data (`true`) or not (`false`, default). When set to `true`, building entrances associated with address features will be included in the response. This includes both permanent and temporary geocoding. **This parameter is in Public Preview.** |

**Examples:**

```sh
mapbox geocoder forward --q Helsinki --limit 1
mapbox geocoder forward --q "1600 Pennsylvania Ave" --country us --types address
```

## `mapbox geocoder reverse`

Looks up the features at a pair of coordinates.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `--longitude` | The `longitude` decimal value from the geographic coordinate for the location being queried. |
| `--latitude` | The `latitude` decimal value from the geographic coordinate for the location being queried. |
| `--permanent` | Specify whether you intend to store the results of the query (`true`) or not (`false`, default). Permanent geocoding allows caching and storing results indefinitely. Requires a valid credit card on file or an active enterprise contract. |
| `--country` | Limit results to one or more countries. Permitted values are [ISO 3166 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes separated by commas. |
| `--language` | Set the language of the text supplied in responses. Also affects result scoring, with results matching the user's query in the requested language being preferred over results that match in another language. For example, an autocomplete query for things that start with `Frank` might return `Frankfurt` as the first result with an English (`en`) language parameter, but `Frankreich` ("France") with a German (`de`) language parameter. |
| `--limit` | Specify the maximum number of results to return. The default is `1` and the maximum supported is `5`. |
| `--types` | Filter results to include only a subset (one or more) of the available feature types. Options are `country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `street`, and `address`. Multiple options can be comma-separated. Values: `country`, `region`, `postcode`, `district`, `place`, `locality`, `neighborhood`, `street`, `block`, `address`, `secondary_address`. |
| `--worldview` | Returns features that are defined differently by audiences that belong to various regional, cultural, or political groups. If `worldview` is not set, the `us` worldview boundaries are returned by default. Values: `ar`, `cn`, `in`, `jp`, `ma`, `rs`, `ru`, `tr`, `us`. |

**Examples:**

```sh
mapbox geocoder reverse --longitude 24.94 --latitude 60.16
mapbox geocoder reverse --longitude -74.0 --latitude 40.7 --types address
```

## `mapbox geocoder batch`

Up to 50 forward or reverse queries in one request.

**Parameters:**

| Parameter | Description |
| --- | --- |
| `--data`/`-d` | Request body as JSON string |
| `--permanent` | Specify whether you intend to store the results of the query (`true`) or not (`false`, default). Permanent geocoding allows caching and storing results indefinitely. Requires a valid credit card on file or an active enterprise contract. |

**Examples:**

```sh
mapbox geocoder batch -d '[
  {"types":["place"],"q":"Helsinki"},
  {"longitude":24.94,"latitude":60.16}
]'
```