October 31, 2025

Localities Reference 2.0

Localities Javascript API Reference 2.0

1. AutocompleteService class
2. AutocompleteLocalities Interface
3. AutocompleteParameters Interface
4. AutocompleteRequest Interface
5. AutocompleteResponse Interface
6. AutocompleteResponseItem Interface
7. ComponentRestrictions Interface
8. DetailsResponseItem Interface
9. ErrorAutocompleteCallback Interface
10. ErrorDetailsCallback Interface
11. MatchedElements Interface
12. MatchedSubstring Interface
13. SuccessAutocompleteCallback Interface
14. SuccessDetailsCallback Interface

AutocompleteService class

woosmap.localities.AutocompleteService

AutocompleteService

Constructor
AutocompleteService	AutocompleteService(key) Parameters: key: String Woosmap Public Key of your project

Methods
autocomplete	autocomplete(params, callbackSuccess, callbackError, debounceTime) Parameters: params: AutocompleteRequest query parameters callbackSuccess: SuccessAutocompleteCallback executed on success callbackError: ErrorAutocompleteCallback executed on failure debounceTime: Number prevents autocomplete requests from being sent unnecessarily often. Default is no debounce. Get the suggestions array from an input value.
getDetails	getDetails(publicId, callbackSuccess, callbackError) Parameters: publicId: String Identifier of the Localities Item callbackSuccess: SuccessDetailsCallback executed on success callbackError: ErrorDetailsCallback executed on failure Get the details of a Localities Item from its public_id.

AutocompleteLocalities Interface

Properties
admin_0	Type: String The country name associated to the prediction
admin_1	Type: String The area name associated to the prediction
description	Type: String The suggested formatted answer
location	Type: LatLngLiteral The location object
name	Type: String The location name
postal_codes	Type: String | String[] Array of postal codes for suggested location (only returned for localities predictions)
postal_town	Type: String The largest city (or the post office city) for a postal_code (only returned for postal_code predictions).
type	Type: String requested prediction type (‘locality’, ‘postal_code’, ‘country’, ‘admin_level’, ‘train_station’, ‘metro_station’, ‘shopping’, ‘airport’, ‘museum’, ‘zoo’, ‘amusement_park’, ‘art_gallery’, ‘tourist_attraction’)
viewpoint	Type: LatLngBoundsLiteral The preferred viewpoint when displaying this Locality on a map. This property will be null if the preferred viewport for the Locality is not known.

AutocompleteParameters Interface

Properties
components	Type: ComponentRestrictions restricts predictions to selected components
customDescription	Type: String | String[] Sets custom description using one or more response field (see AutocompleteLocalities object Specification). Selected field should be string or array of string. Field ‘description’ can not be selected.
data	Type: String Defaults to ‘standard’, can be set to ‘advanced’ to retrieve postal codes outside western Europe
debounceTime	Type: Number prevents autocomplete requests from being sent unnecessarily often. Default is no debounce.
extended	Type: String can be set to ‘postal_code’ to search localities by name or postal codes
firstTabIndex	Type: Number all tabindexes in Autocomplete will start from that tabindex. Defaults to 0.
language	Type: String expected response language. Default is the country local or browser language
minLength	Type: Number Number of characters before sending request to Localities API
types	Type: String | String[] The types queried (example ‘locality’, ‘postal_code’, ‘country’ ; omit param for ‘locality’ + ‘postal_code’)

AutocompleteRequest Interface

Properties
components	Type: ComponentRestrictions restricts suggestions to selected components
customDescription	Type: String This parameter allows to choose the description format for all or some of the suggestion types selected. The custom formats are described as follows: JavaScript custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"
data	Type: String Defaults to ‘standard’, can be set to ‘advanced’ to retrieve postal codes outside western Europe
extended	Type: String can be set to ‘postal_code’ to search localities by name or postal codes
input	Type: String User input
language	Type: String expected response language. Default is the country local or browser language
types	Type: String | String[] The types queried (example ‘locality’, ‘postal_code’, ‘country’ ; omit param for ‘locality’ + ‘postal_code’)

AutocompleteResponse Interface

Properties
localities	Type: AutocompleteResponseItem Array with Autocomplete items

AutocompleteResponseItem Interface

Properties
description	Type: String The suggested formatted answer
matched_substrings	Type: array Contains an array with offset value and length. These describe the location of the entered term in the prediction result text, so that the term can be highlighted if desired.
public_id	Type: String Item identifier
type	Type: String requested suggestion type (‘locality’, ‘postal_code’, ‘country’, ‘admin_level’, ‘train_station’, ‘metro_station’, ‘shopping’, ‘airport’, ‘museum’, ‘zoo’, ‘amusement_park’, ‘art_gallery’, ‘tourist_attraction’, ‘address’)

ComponentRestrictions Interface

Properties
country	Type: String | String[] Restricts suggestions to the specified country (ISO 3166-1 Alpha-2 country code, case insensitive). For example, ‘fr’, ‘gb’, or ‘es’. You can provide a single one, or an array of country code strings.

DetailsResponseItem Interface

Properties
address_components	Type: array Array containing the separate components applicable to this address. Each component has a long name (full text description or name of the address component), a short name (abbreviated textual name for the address component, if available) and types (array indicating the type of the address component like locality, street_number…)
formatted_address	Type: string String containing the human-readable address of this item.
geometry	Type: object Item geometry ({location:{lat, lng}, viewport: {northeast: {lat, lng}, southwest: {lat, lng}}})
name	Type: string Item name
public_id	Type: string Item identifier
types	Type: array Types of the given item (like locality or postal_code)

ErrorAutocompleteCallback Interface

Type: Function

Callback executed when autocomplete query fails

Function
ErrorAutocompleteCallback	ErrorAutocompleteCallback(errorCode, errorText) Parameters: errorCode: Number the http error code errorText: String the error description Callback executed when autocomplete query fails

ErrorDetailsCallback Interface

Type: Function

Callback executed when details query fails

Function
ErrorDetailsCallback	ErrorDetailsCallback(errorCode, errorText) Parameters: errorCode: Number the http error code errorText: String the error description Callback executed when details query fails

MatchedElements Interface

Properties
description	Type: MatchedSubstring[] (optional) A set of substrings that match the description field

MatchedSubstring Interface

Properties
length	Type: Number The length of the substring
offset	Type: Number The offset to the substring’s start within the AutocompleteLocalities field string

SuccessAutocompleteCallback Interface

Type: Function

Callback executed when autocomplete query is successful

Function
SuccessAutocompleteCallback	SuccessAutocompleteCallback(autocompleteResponse) Parameters: autocompleteResponse: AutocompleteResponse Callback executed when autocomplete query is successful

SuccessDetailsCallback Interface

Type: Function

Callback executed when details query is successful

Function
SuccessDetailsCallback	SuccessDetailsCallback(autocompleteResponse) Parameters: autocompleteResponse: DetailsResponseItem Callback executed when details query is successful

Was this article helpful?

Have more questions? Submit a request