The Localities fields name, location, admin_0, admin_1, admin_2, viewpoint, postal_codes, postal_town and iata_code are deprecated and replaced with new properties as of March 31, 2022, and will be turned off on March 31, 2023.
These fields are deprecated in the Localities API Autocomplete endpoint, Localities JS Widget, and Localities JS API. This guide shows you how to update your code to stop using these fields.
What do you need to change?
So far, a call to Localities Autocomplete provided you with all available fields.
Now, to benefit from the same attributes, you’ll need to perform two requests.
Once a locality has been returned in an autocomplete response, its public_id can be used to request additional details about that locality, such as its complete address, geographical position, etc… by performing a Localities Details request.
Some of the deprecated fields still have the same attributes name whereas other change. Here is a table of correspondence between the deprecated fields from autocomplete suggestion and the new fields from details response.
| Autocomplete Fields (deprecated) | Details Fields |
|---|---|
name |
name |
location |
geometry.location |
viewpoint |
geometry.viewport |
admin_0 |
address_components.types['administrative_area_level_0"].long_name |
admin_1 |
address_components.types["administrative_area_level_1"].long_name |
admin_2 |
address_components.types["administrative_area_level_2"].long_name |
postal_codes |
address_components.types["postal_codes"].long_name |
postal_town |
address_components.types["postal_town"].long_name |
iata_code |
address_components.types["iata_code"].long_name |
Custom Description
To display suggestions from an autocomplete search, it is recommended to use the field description. By default, this field concatenates the name, admin_1, and admin_0 (for postal codes the description is composed of name, postal_town and admin_0).
In some cases, the displayed suggestion may have been built based on deprecated fields. To ease the migration and allow to display suggestions with a custom description, the Localities API now have a new parameter called custom_description to build as follow:
custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"
Localities JS API and Localities JS Widget have dedicated method to implement this parameter as detailed below.
Migrating Autocomplete Deprecated Fields
This section shows how to update your code to get the fields from the localities details request formerly returned in an autocomplete response.
Localities API /autocomplete endpoint
If you’ve implemented autocompletion using the Localities REST API and use one of the deprecated field, you’ll need to perform a details request passing it the public_id from desired suggestion.
Here is an example of chaining the two requests and benefit from fields returned in details response.
function autocompleteLocalities(input, woosmap_key) {
return fetch(
`https://api.woosmap.com/localities/autocomplete/?key=${woosmap_key}&input=${input}`
).then((response) => response.json());
}
function getDetailsLocalities(public_id, woosmap_key) {
return fetch(
`https://api.woosmap.com/localities/details/?$key=${woosmap_key}&public_id=${public_id}`
).then((response) => response.json());
}
autocompleteLocalities("London", woosmap_key).then(({localities}) => {
getDetailsLocalities(localities[0].public_id, woosmap_key).then((localityDetails) => {
const latlngLocality = {
lat: localityDetails.result.geometry.location.lat;
lng: localityDetails.result.geometry.location.lng;
};
})
})
Check this live example which implements this concept in a similar way:
Localities JS API
The existing Localities JS API is now currently deprecated and tagged as the v1 version. To migrate to new fields, you’ll have to implement the v2 and instead of retrieving the fields from the AutocompleteLocalities Object, use the method AutocompleteService.getDetails() to get details from the autocomplete suggestion selected, using the suggestion’s public_id.
<script src="https://sdk.woosmap.com/localities/localities.2.0.js"></script>
<script>
const autocompleteService = new woosmap.localities.AutocompleteService(key);
autocompleteService.autocomplete({input: "London"}, ({localities}) => {
autocompleteService.getDetails(localities[0].public_id, (localityDetails) => {
const latlngLocality = {
lat: localityDetails.geometry.location.lat;
lng: localityDetails.geometry.location.lng;
};
});
}
);
</script>
If you would like to build a custom_description, you can pass it to the AutocompleteService.autocomplete() method as a parameter.
Check this live example:
Localities JS Widget
The existing Localities JS Widget is now currently deprecated and tagged as the v1 version. To migrate to new fields, you’ll have to implement the v2 and instead of retrieving the fields from the AutocompleteLocalities Object, use the method Autocomplete.getSelectedSuggestionDetails() to get details from the autocomplete suggestion selected, using the suggestion’s public_id.
<input id="my-input-localities" placeholder="Search..." autocomplete="off"/>
<link rel="stylesheet" href="https://sdk.woosmap.com/localities/style.2.0.css"/>
<script src="https://sdk.woosmap.com/localities/localitieswidget.2.0.js?key=woos-xxxx"></script>
<script>
const localitiesWidget = new woosmap.localities.Autocomplete("my-input-localities")
localitiesWidget.addListener("selected_suggestion", () => {
const localityDetails = localitiesWidget.getSelectedSuggestionDetails();
const latlngLocality = {
lat: localityDetails.geometry.location.lat;
lng: localityDetails.geometry.location.lng;
};
});
</script>
If you would like to set a custom description, you can specify it with AutocompleteParameters.customDescription when building the Autocomplete Widget instance.
You can also note in v2, the CSS is no longer part of the library so you have to manually add the external CSS file. This is more convenient if you would like to use your own style.
Check this live example:
Please, don’t hesitate to reply in this thread if you need more help on migrating your code.