Source: https://developers.woosmap.com/products/map-api/services/localities-geocode/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Work with Localities



## Overview

The [`LocalitiesService class`](/products/map-api/reference/1.4/#woosmap.map.LocalitiesService) provides methods for using the Localities API through Woosmap Map JavaScript API. It supports modern usage patterns such as [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises).

This guide focus [Localities Geocode](/products/localities/features/geocoding/) which provides location for addresses and vice versa.

Review the example below to see how to use this service for geocoding and reverse geocoding using the Woosmap Map JS API:

https://demo.woosmap.com/js-samples/samples/localities-geocode/app/dist/
[](https://demo.woosmap.com/js-samples/samples/localities-geocode/highlight/highlight.html "Open in new tab with highlighted code")
Try sample 

- [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-geocode/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-geocode/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-geocode)

## Getting started

Before using the Localities service in the Map JavaScript API, it is required to have a [secure and valid Woosmap API key](/api-reference/authentication/) and enable the Localities API for it.

Next, you must load the Map JS API library by including a script tag in your HTML page as follows:

```html
<script async src="https://sdk.woosmap.com/map/map.js?key=YOUR_API_KEY&callback=initMap"></script>
```

See the [Get Started with Map JS API](/products/map-api/get-started/) guide for more information.

## Geocode and Reverse Geocode

### Request Localities Geocode

To initiate a request to Localities Geocode in the Woosmap Map JS API, create an object of type `woosmap.map.LocalitiesService` and call `LocalitiesService.geocode()`, passing it a [`LocalitiesGeocodeRequest`](/products/map-api/reference/1.4/#woosmap.map.localities.LocalitiesGeocodeRequest) object literal.

The `LocalitiesGeocodeRequest` object literal requires either an `address` string to perform a geocode request or a `latlng` object for a reverse geocode request. It contains the following fields:

```plaintext
{
    address?: string,
    components?: LocalitiesComponentRestrictions,
    countryCodeFormat?: string, //'alpha2' | 'alpha3'
    data?: LocalitiesRequestData,
    fields?: string,
    language?: string,
    latLng?: LatLng | LatLngLiteral,
}
```

- `address` (optional): The input string to geocode. Can represent an address, a street, a locality, or a postal code.
- `components` (optional): Used to filter over countries. Countries must be passed as an ISO 3166-1 Alpha-2 or Alpha-3 compatible country code.
- `countryCodeFormat` (optional): To specify the format for the short country code expected to be returned in the `address_components` field. Default is the format used to specify components or alpha2 if no components are specified.
- `data` (optional): Whether to retrieve suggestions to worldwide postal codes in addition to postal codes for Western Europe.
- `fields` (optional): Used to limit the returning fields when `type=address`. By default, and for other types localities, all fields are returned. Only one field is available: `geometry`.
- `language` (optional): The language code, using ISO 3166-1 Alpha-2 country codes, indicating in which language the results should be returned, if possible. If language is not supplied, the Localities service will use English as the default language. No language necessary for postal\_code request.
- `latLng` (optional): The latLng parameter is used for reverse geocoding, it’s required if the address parameter is missing.

Below is a sample `LocalitiesGeocodeRequest` for reverse geocoding:

```javascript
const reverseGeocodeRequest = {
  latlng: { lat: 43.61, lng: 3.876 },
  language: "fr",
  components: { country: ["FR"] },
};
```

The `LocalitiesService`’s `geocode()` method is asynchronous and returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) object that is either fulfilled with a [`LocalitiesPredictions`](/products/map-api/reference/1.4/#woosmap.map.localities.LocalitiesGeocodeResponse) object or rejected with an `APIError` object. You can attach handlers to this Promise object to process results upon operation success or failure.

```javascript
const localitiesService = new woosmap.map.LocalitiesService();
localitiesService
  .geocode(reverseGeocodeRequest)
  .then((response) => {
    console.log(response.results);
  })
  .catch((error) => {
    console.log(error);
  })
  .finally(() => {
    console.log("done");
  });
```

### Localities Geocode Response

A successful `geocode()` call returns a `LocalitiesGeocodeResponse` object with a `result` field, which contains same field as a [`LocalitiesDetailsResponse`](/products/map-api/services/localities-autocomplete-details/#localities-details-response).