Autocomplete Requests

How to build your Localities API autocomplete requests

  1. Overview
  2. Required Parameters
  3. Optional parameters
  4. Localities Suggestions Responses
  5. Suggestions Fields

The Localities Autocomplete provides worldwide suggestions for a for text-based geographic searches.

It can match on full words as well as substrings. You can therefore send queries as the user types, to provide on-the-fly suggestions such as city names, postal codes, suburb names or addresses.

The returned suggestions are designed to be presented to the user to aid them in selecting their desired location. If you want to get more information on one of the suggestions, you must send a /Details request using its public_id .

Overview

A Woosmap Localities /autocomplete request is an HTTP URL of the following form:

https://api.woosmap.com/localities/autocomplete/?parameters

Required Parameters

Certain parameters are required to initiate a Localities request. As is standard in URLs, all parameters are separated using the ampersand (&) character. The list of parameters and their possible values are enumerated below.

https://api.woosmap.com/localities/autocomplete/?input=london&key={PUBLIC_API_KEY}

input

The text string on which to search. Localities API will return candidate matches based on this string and order results based on their perceived relevance.

key

Your project’s API key. This key identifies your Woosmap Project for purposes of quota management.

To use the Localities API, your Public API key (parameter key) has to be authorized for the domains and/or IPs (referer) where you make the call. More on securing API keys here.

Optional parameters

.../localities/autocomplete/?input=lond&key=[YOUR_API_KEY]&types=postal_code&components=country:gb&language=en&data=advanced

types

The types of suggestion to return. Several types are available, see the list below:

locality includes locality names (from city to village) and suburbs
postal_code publicly-used postal codes around the world
address addresses (only available for UK and France)
admin_level most commonly used administrative areas
country countries as whole point of interest
airport includes all medium sized to international sized airports
train_station includes all train stations
metro_station includes all metro stations
shopping includes shopping malls (or “shopping centers”) - may include private retail brands
museum includes museums
tourist_attraction includes tourist attractions like the Eiffel tower
amusement_park includes amusement parks like Disneyland Paris
art_gallery includes art galleries
zoo includes zoos

Not specifying any type will only query locality and postal_code. Multiple types can be passed using the pipe character (|) as a separator. For example: types=locality|airport|admin_level.

components

A grouping of places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries must be passed as a two character, ISO 3166-1 Alpha-2 or Alpha-3 compatible country code. For example: components=country:fr or components=country:fra would restrict your results to places within France and components=country:fr-fr returns locations only in Metropolitan France. Multiple countries must be passed as multiple country:XX filters, with the pipe character (|) as a separator. For example: components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to city names or postal codes within the United Kingdom, France, Belgium, Spain and Italy.

language

The language code, indicating in which language the results should be returned, if possible. If language is not supplied, the Localities service will use english as default language. No language necessary for postal_code request.

data

Two values for this parameter: standard or advanced. By default, if the parameter is not defined, value is set as standard. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. A dedicated option subject to specific billing on your license is needed to use this parameter. Please contact us if you are interested in using this parameter and you do not have subscribed the proper option yet.

extended

This parameter is available only for France and Italy and is intended to be used along with the locality type and an existing postal code entered as an input. It allows retrieving the complete list of suggestions of locality type that includes this postal code. In that case, the autocomplete endpoint can return more than 5 suggestions. It is recommended to activate this parameter along with the locality type only to avoid duplicate locations. Also, the default description returned by the API changes to name (postal code), admin_1, admin_0.

custom_description

This parameter allows to choose the description format for all or some of the suggestion types selected. The custom formats are described as follows:

custom_description=type_A:"{field_1}, {field_2}, [...]"|type_B:"{field_1}, {field_2}, [...]"

Available fields to build your custom_description depend on the returned type.

Corresponding types/fields table:

  name administrative_area_level_0 administrative_area_level_1 administrative_area_level_2 postal_codes postal_town locality iata_code
locality    
postal_code        
admin_level            
country              
airport          
train_station      
metro_station      
shopping      
museum      
tourist_attraction      
amusement_park      
art_gallery      
zoo      

Here is an example for locality and postal_code types:

custom_description=locality:"{name} - {administrative_area_level_0}"|postal_code:"{name} ({administrative_area_level_1})"

Suggestions of type locality will look like München - Germany, instead of the default format: München, Bayern, Germany

Suggestions of type postal_code will look like SW6 1HN (City of London), instead of the default format: SW6 1HN, City of London, United Kingdom

Localities Suggestions Responses

Localities autocomplete provides a JSON response containing one root element, localities which contains an array of up to 5 suggestions sorted from most to least relevant.

{
  "localities": [
        {
            "public_id": "SRji5gQLTz9EznRhLkjD/1pYWLQ=",
            "description": "SW6 1HL, City of London, United Kingdom",
            "type": "postal_code",
            "matched_substrings": {
                "description": [
                    {"offset": 17, "length": 6}
                ],
                [...]
            },
            "has_addresses": true,
            [...]
        },
        {
            "public_id": "Ch6qA8cLmvyvEEoFy6nYeFcEdNU=",
            "description": "London, City of London, United Kingdom",
            "type": "locality",
            "matched_substrings": {
                "description": [
                    {"offset": 0,"length": 6},
                    {"offset": 16,"length": 6}
                ],
                [...]
            },
            [...]
        }
  ]
}

Suggestions Fields

Suggestion results can contain the following fields:

public_id

Contains a unique ID for each suggestion. This ID is required to perform Localities Details request.

description

The description of the suggestion. The description format vary depending on the type of the retrieved object. You can customize the description format using the custom_description param.

type

Contains the type of the suggestion, See the list of existing types).

matched_substrings

Contains a set of substrings that match elements in the input. It can be used to highlight those substrings. Each substring is identified by an offset and a length.

name

Contains the human-readable name for the returned result. For postal_code results, this is directly the postal code value. For locality results, name in the specified language is returns. If no language is specified, default name (country local language) is returned.

Notice : name is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field name in the Details endpoint instead.

location

Contains latitude and longitude of the searched city or postal code. For postal_code results, coordinates represent the center of the area. For locality results, coordinates represent the center of the populated area.

Notice : location is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field geometry.location in the Details endpoint instead

admin_0

Contains the country name.

Notice : admin_0 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_0 in the Details endpoint instead

admin_1

Contains the administrative level including the suggestion.

Notice : admin_1 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_1 in the Details endpoint instead

admin_2

For small locality type points of interests (suburbs, neighborhoods, villages), contains the municipality it belongs to.

Notice : admin_2 is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : administrative_area_level_2 in the Details endpoint instead

viewpoint

Contains geographic bounds (north, south, east, west) to help center a map on a suggestion’s selection by the user.

Notice : viewpoint is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field geometry.viewport in the Details endpoint instead

postal_codes

Contains an array of known postal codes for a locality (only available on suggestions with country:fr for France or it for Italy and type: locality).

Notice : postal_codes is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : postal_codes in the Details endpoint instead

postal_town

Contains the larger city (or the post office city) for a postal_code (only available on suggestions with type: postal_code).

Notice : postal_town is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : postal_town in the Details endpoint instead

iata_code

Contains the International Air Transport Association (IATA) code of an airport (only available on suggestions with type: airport)

Notice : iata_code_ is deprecated as of March 31, 2022, and will be turned off on March 31, 2023. Use the field long_name of the address_component with type : iata_code in the Details endpoint instead

Was this article helpful?
Have more questions? Submit a request