> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/mapbox-search-js/llms.txt)

# Geocoding

This page includes reference documentation for the Geocoding feature in the **Mapbox Search JS Core** framework.

## Class

### GeocodingCore

A `GeocodingCore` object is an application's main entrypoint to the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/). The Geocoding API allows forward (location to coordinates) and reverse (coordinates to location) queries, enabled by corresponding methods from the `GeocodingCore` object.

A [Mapbox access token](https://docs.mapbox.com/help/glossary/access-token/) is required to use `GeocodingCore`, and other options may be specified either in the constructor or in the [GeocodingCore#forward](#geocodingcore#forward) or [GeocodingCore#reverse](#geocodingcore#reverse) calls.

> new GeocodingCore(options: <a href="#geocodingoptions">GeocodingOptions</a>?)

#### Import[​](#import)

```javascript
import { GeocodingCore } from '@mapbox/search-js-core'
```

#### Parameters

| Name | Description |
| --- | --- |
| **options** [GeocodingOptions](#geocodingoptions)?  |  |
| **options.accessToken** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?  |  |

#### Example

```js
const geocode = new GeocodingCore({ accessToken: 'pk.my-mapbox-access-token' });

const results = await geocode.forward('Washington D.C.');
if (results.features.length === 0) return;

const feature = results.features[0];
doSomethingWithCoordinates(feature);
```

#### Instance Members

##### accessToken

The [Mapbox access token](https://docs.mapbox.com/help/glossary/access-token/) to use for all requests.

###### Type

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

##### defaults

Any default options ([GeocodingOptions](#geocodingoptions)) to be merged into options in the following methods:

-   [GeocodingCore#forward](#geocodingcore#forward)
-   [GeocodingCore#reverse](#geocodingcore#reverse)

###### Type

Partial<[GeocodingOptions](#geocodingoptions)>

### Programmatic search

##### forward()

[GeocodingCore#forward](#geocodingcore#forward) allows you to look up a feature by name and returns the feature(s) and corresponding geographic coordinates in [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) format.

**Legal terms:**

Due to legal terms from our data sources, geographic coordinates should be used ephemerally and not persisted. If the results are to be cached/stored in a customer database, calls to [GeocodingCore#forward](#geocodingcore#forward) should specify `permanent: true` within the method options argument.

This permanent policy is consistent with the [Mapbox Terms of Service](https://www.mapbox.com/tos/) and failure to comply may result in modified or discontinued service.

Additionally, the [Mapbox Terms of Service](https://www.mapbox.com/tos/) states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).

**Disclaimer:**

The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.

###### Parameters

| Name | Description |
| --- | --- |
| **searchText** [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  |  |
| **optionsArg** [GeocodingOptions](#geocodingoptions)?  |  |
| **optionsArg.signal** AbortSignal?  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[GeocodingResponse](#geocodingresponse)>

#### Import[​](#import)

```javascript
import { forward } from '@mapbox/search-js-core'
```

###### Example

```js
const results = await geocode.forward('Washington D.C.');
if (results.features.length === 0) return;

const feature = results.features[0];
doSomethingWithCoordinates(feature);
```

##### reverse()

[GeocodingCore#reverse](#geocodingcore#reverse) allows you to look up a single pair of coordinates and returns the geographic feature or features that exist at that location in [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) format.

**Legal terms:**

Due to legal terms from our data sources, geographic coordinates should be used ephemerally and not persisted. If the results are to be cached/stored in a customer database, calls to [GeocodingCore#reverse](#geocodingcore#reverse) should specify `permanent: true` within the method options argument.

This permanent policy is consistent with the [Mapbox Terms of Service](https://www.mapbox.com/tos/) and failure to comply may result in modified or discontinued service.

Additionally, the [Mapbox Terms of Service](https://www.mapbox.com/tos/) states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).

**Disclaimer:**

The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.

###### Parameters

| Name | Description |
| --- | --- |
| **lngLat** ([String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [LngLatLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatlike))  |  |
| **optionsArg** [GeocodingOptions](#geocodingoptions)?  |  |
| **optionsArg.signal** AbortSignal?  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[GeocodingResponse](#geocodingresponse)>

#### Import[​](#import)

```javascript
import { reverse } from '@mapbox/search-js-core'
```

###### Example

```js
const results = await geocode.reverse({ lat: 40.7736, lng: -73.9749 });
if (results.features.length === 0) return;

const feature = results.features[0];
doSomethingWithFeature(feature);
```

### Interactive search

##### suggest()

[GeocodingCore#suggest](#geocodingcore#suggest) is a managed endpoint for an interactive [SearchSession](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#searchsession), such as one operated through a web or React component. It accepts a search text string for either a [GeocodingCore#forward](#geocodingcore#forward) or [GeocodingCore#reverse](#geocodingcore#reverse) geocoding query and returns a [GeocodingResponse](#geocodingresponse) object.

###### Parameters

| Name | Description |
| --- | --- |
| **searchText** [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  |  |
| **optionsArg** [GeocodingOptions](#geocodingoptions)?  |  |
| **optionsArg.signal** AbortSignal?  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[GeocodingResponse](#geocodingresponse)>

#### Import[​](#import)

```javascript
import { suggest } from '@mapbox/search-js-core'
```

###### Example

```js
const result = await geocode.suggest('123 Main St');
if (results.features.length === 0) return;

const feature = results.features[0];
doSomethingWithCoordinates(feature);
```

##### retrieve()

[GeocodingCore#retrieve](#geocodingcore#retrieve) is a managed endpoint for an interactive [SearchSession](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/search_session/#searchsession), such as one operated through a web or React component. It accepts a [GeocodingFeature](#geocodingfeature) object and returns the same object. It is used in a SearchSession to respond to a user's selection of a feature suggestion. Unlike the Search Box API, the Geocoding API returns all feature data in the initial response, so this method does not perform any further data retrieval.

###### Parameters

| Name | Description |
| --- | --- |
| **suggestion** [GeocodingFeature](#geocodingfeature)  |  |

###### Returns

[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<[GeocodingFeature](#geocodingfeature)>

Was this section on GeocodingCore helpful?[Yes](null)[No](null)

## Options and Type Definitions

### GeocodingOptions

Options object for configuring [GeocodingCore](#geocodingcore), mapped to [Geocoding API](https://docs.mapbox.com/api/search/geocoding/) parameters.

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

<table class="table table--fixed table--compact" style="width:100%;table-layout:fixed"><colgroup><col width="28%"><col></colgroup><thead><tr class="bg-gray-faint"><th style="border-top-left-radius:4px">Name</th><th style="border-top-right-radius:4px">Description</th></tr></thead><tbody><tr><td><strong>autocomplete</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;</td><td><span>When autocomplete is enabled, results will be included that start with the requested string, rather than just responses that match it exactly.<p>Defaults to true.</p></span></td></tr><tr><td><strong>bbox</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="/mapbox-search-js/api/core/geography/#lnglatboundslike">LngLatBoundsLike</a>)</span>&nbsp;</td><td><span>Limit results to only those contained within the supplied bounding box.</span></td></tr><tr><td><strong>country</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Limit results to one or more countries. Permitted values are <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166 alpha 2</a> country codes separated by commas.</span></td></tr><tr><td><strong>language</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>An <a href="https://en.wikipedia.org/wiki/IETF_language_tag">IETF language tag</a> that controls the language of the text supplied in responses, and also affects result scoring.</span></td></tr><tr><td><strong>limit</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a></span>&nbsp;</td><td><span>The number of results to return, up to <code>10</code> .<p>Defaults to 5.</p></span></td></tr><tr><td><strong>permanent</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean">boolean</a></span>&nbsp;</td><td><span>Permanent geocodes are used for use cases that require storing data indefinitely. If 'true', requests will be made with permanent enabled. Separate billing for permanent geocoding will apply.<p>If undefined or 'false', the geocoder will default to use temporary geocoding. Temporary geocoding results are not allowed to be cached.</p><p>For questions related to permanent resource usage and billing, contact <a href="https://www.mapbox.com/contact/sales/">Mapbox sales</a>.</p></span></td></tr><tr><td><strong>proximity</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="/mapbox-search-js/api/core/geography/#lnglatlike">LngLatLike</a>)</span>&nbsp;</td><td><span>Bias the response to favor results that are closer to this location.<p>Provided as two comma-separated coordinates in longitude,latitude order, or the string <code>ip</code> to bias based on reverse IP lookup.</p></span></td></tr><tr><td><strong>types</strong>&nbsp;<span>(<a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a> | <a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set">Set</a>&lt;<a href="#featuretypes">FeatureTypes</a>&gt;)</span>&nbsp;</td><td><span>Filter results to include only a subset (one or more) of the available feature types. Multiple options can be comma-separated.</span></td></tr><tr><td><strong>worldview</strong>&nbsp;<span><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String">string</a></span>&nbsp;</td><td><span>Available worldviews are: <code>cn</code> , <code>in</code> , <code>jp</code> , <code>us</code> . If a worldview is not set, <code>us</code> worldview boundaries will be returned.</span></td></tr></tbody></table>

Was this section on GeocodingOptions helpful?[Yes](null)[No](null)

### GeocodingResponse

A `GeocodingResponse` object represents a returned data object from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object).

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **attribution** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Attributes the results of the Mapbox Geocoding API to Mapbox. |
| **features** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[GeocodingFeature](#geocodingfeature)>  | The returned feature objects. |
| **type** `"FeatureCollection"`  | `"FeatureCollection"` , a GeoJSON type from the [GeoJSON specification](https://tools.ietf.org/html/rfc7946) . |

Was this section on GeocodingResponse helpful?[Yes](null)[No](null)

### GeocodingFeature

A `GeocodingFeature` object represents a [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) feature result from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/).

**Legal terms:**

Due to legal terms from our data sources, results from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/) should use the `permanent=true` flag if the results are to be cached/stored in a customer database. Otherwise, results should be used ephemerally and not persisted.

This permanent policy is consistent with the [Mapbox Terms of Service](https://www.mapbox.com/tos/) and failure to comply may result in modified or discontinued service.

Additionally, the [Mapbox Terms of Service](https://www.mapbox.com/tos/) states any rendering of a feature suggestion must be using Mapbox map services (for example, displaying results on Google Maps or MapKit JS is not allowed).

**Disclaimer:**

The failure of Mapbox to exercise or enforce any right or provision of these Terms will not constitute a waiver of such right or provision.

#### Type

any

#### Static Members

##### id

Feature id. This property is named "id" to conform to the GeoJSON specification, but is the same id referred to as mapbox_id within the properties object.

###### Type

[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)

#### Related

-   [Geocoding response object](https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object)

Was this section on GeocodingFeature helpful?[Yes](null)[No](null)

### GeocodingFeatureProperties

Raw [GeoJSON](https://docs.mapbox.com/help/glossary/geojson/) feature properties from the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/).

Reference: [https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object](https://docs.mapbox.com/api/search/geocoding-v6/#geocoding-response-object)

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **bbox** [LngLatBoundsLike](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/geography/#lnglatboundslike)  | A bounding box for the feature. This may be significantly larger than the geometry. This property is only provided with features of type `country` , `region` , `postcode` , `district` , `place` , `locality` , or `neighborhood` . |
| **context** Partial<[GeocodingFeatureContext](#geocodingfeaturecontext)>  | Object representing the hierarchy of encompassing parent features. |
| **coordinates** [Coordinates](#coordinates)  | Coordinate and accuracy data for a geographic feature. |
| **feature_type** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string describing the geographic type of the feature. See [FeatureTypes](#featuretypes) for supported options. |
| **full_address** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The full feature text string, combining `name_preferred` and `place_formatted` . |
| **mapbox_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Feature id. The `mapbox_id` uniquely identifies a feature in the Mapbox search database. Mapbox ID's are accepted in requests to the Geocoding API as a forward search, and will return the feature corresponding to that id. |
| **match_code** [MatchCode](https://docs.mapbox.com/mapbox-search-js/mapbox-search-js/api/core/autofill/#matchcode)  | Match codes for each context component of an address, plus an overall match confidence. Provides an indication of how well each part of the address matched the query. |
| **name** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Formatted string of the most granular geographical component of the feature. For example, for an address this will be the address number and street. For features known by multiple aliases, this field will represent the alias, if one is available, matching the queried text. |
| **name_preferred** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Similar to `name` , except this will always be the canonical or otherwise more common alias for the feature name. For example, searching for "America" will return "America" as the `name` , and "United States" as name_preferred. |
| **place_formatted** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | Formatted string of the feature context (e.g. `place` + `region` + `country` + `postcode` + `counry` ). The part of the full feature name which comes after `name` . |

Was this section on GeocodingFeatureProperties helpful?[Yes](null)[No](null)

### GeocodingFeatureContext

Object representing the hierarchy of encompassing parent features for a given [GeocodingFeature](#geocodingfeature).

#### Type

{address: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), street: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), neighborhood: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), postcode: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), locality: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), place: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), district: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), region: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent), country: [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)}

#### Properties

| Name | Description |
| --- | --- |
| **address** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **country** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **district** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **locality** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **neighborhood** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **place** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **postcode** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **region** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |
| **street** [GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)  |  |

#### Static Members

##### address

Address context component. Includes separate `address_number` and `street_name` properties.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### street

Street context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### neighborhood

Neighborhood context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### postcode

Postcode context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### locality

Locality context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### place

Place context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### district

District context component.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### region

Region context component. If available, may include additional `region_code` and `region_code_full` properties.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

##### country

Country context component. Includes additional `country_code` and `country_code_alpha_3` properties.

###### Type

[GeocodingFeatureContextComponent](#geocodingfeaturecontextcomponent)

###### Related

-   [https://en.wikipedia.org/wiki/ISO_3166-1](https://en.wikipedia.org/wiki/ISO_3166-1)

Was this section on GeocodingFeatureContext helpful?[Yes](null)[No](null)

### GeocodingFeatureContextComponent

Object representing one level of hierarcy among encompassing parent features for a given [GeocodingFeature](#geocodingfeature).

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **mapbox_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The unique Mapbox ID of the context feature. |
| **name** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A string representing the feature in the requested language, if specified. |
| **wikidata_id** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The [Wikidata](https://wikidata.org/) identifier for the returned feature. |

Was this section on GeocodingFeatureContextComponent helpful?[Yes](null)[No](null)

### FeatureTypes

Geographic feature data types for the [Mapbox Geocoding API](https://docs.mapbox.com/api/search/geocoding-v6/).

#### Type

(`"country"` \| `"region"` \| `"postcode"` \| `"district"` \| `"place"` \| `"locality"` \| `"neighborhood"` \| `"street"` \| `"block"` \| `"address"` \| `"secondary_address"`)

#### Related

-   [https://docs.mapbox.com/api/search/geocoding-v6/#geographic-feature-types](https://docs.mapbox.com/api/search/geocoding-v6/#geographic-feature-types)

Was this section on FeatureTypes helpful?[Yes](null)[No](null)

### Coordinates

Coordinate and accuracy data for a geographic feature.

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **accuracy** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | A coordinate accuracy indicator for address features. Can be one of `rooftop` , `parcel` , `point` , `interpolated` , `approximate` . |
| **latitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The latitude of the feature. |
| **longitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The longitude of the feature. |
| **routable_points** [Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)<[RoutablePoint](#routablepoint)>  | Routable point data for an address feature. |

Was this section on Coordinates helpful?[Yes](null)[No](null)

### RoutablePoint

Routable point data for an address feature.

#### Type

[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)

#### Properties

| Name | Description |
| --- | --- |
| **latitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The latitude of the routable point. |
| **longitude** [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)  | The longitude of the routable point. |
| **name** [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)  | The name of the routable point. |

Was this section on RoutablePoint helpful?[Yes](null)[No](null)