Work with Localities

Use the LocalitiesService to geocode addresses and reverse geocode locations.

Overview
Getting started
Geocode and Reverse Geocode

Overview

The LocalitiesService class provides methods for using the Localities API through Woosmap Map JavaScript API. It supports modern usage patterns such as Promises.

This guide focus Localities Geocode 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:

Getting started

Before using the Localities service in the Map JavaScript API, it is required to have a secure and valid Woosmap API key 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:

        <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 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 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:

        {
    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:

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

The LocalitiesService’s geocode() method is asynchronous and returns a Promise object that is either fulfilled with a LocalitiesPredictions object or rejected with an APIError object. You can attach handlers to this Promise object to process results upon operation success or failure.

        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.

‹ Localities Autocomplete and Details Stores Search ›

Was this article helpful?

Have more questions? Submit a request