Community Forum

Autocomplete Requests

Autocomplete as the user types
  1. Overview
  2. Required Parameters
  3. Optional parameters
  4. Localities Autocomplete example
  5. Response
  6. Samples
  7. Usage limits

Overview

The Localities Autocomplete endpoint provides worldwide suggestions 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 users to help 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 .

Autocomplete endpoint is for autocompletion purposes only. Response content of this endpoint is designed to present suggestions to users while they are typing and request details to the dedicated endpoint. Under no conditions, Autocomplete responses can be used to automatically fill a form, splitted to feed an address database or displayed as a final result. For any other purposes than getting suggestions, the Details endpoint must be used. In case of non compliance, every Autocomplete request will be charged as a Details request.

Autocomplete and details on address and postal_code may be subject to specific product activation. Please see coverage page for more details.

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

Autocompletion is done based on this string.

key

Your project’s API key. This key identifies your Woosmap Project for purposes of security and quota management. Public keys are designed to be used client-side, where every request contains a referer. Alternatively, you can use the private_key parameter for server-side requests.

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

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

private_key

Your project’s private API key. This key identifies your Woosmap Project for purposes of security and quota management. Private keys are designed to be used server-side, where no referer checkings are performed.

You must use the key parameter OR the private_key parameter. Sending both keys will result in an error.

Optional parameters

types

The types of suggestions to return. Below are the most commonly used types; the complete list is available here:

locality includes locality names (from city to village) and suburbs
postal_code publicly-used postal codes around the world
address addresses
admin_level most commonly used administrative areas
country countries as whole point of interest

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

Example
        https://api.woosmap.com/localities/autocomplete/?input=london&key={PUBLIC_API_KEY}&types=locality|airport|admin_level

excluded_types

Specifies types of locations to exclude. Multiple types should be separated using the pipe character (|).

Example
        https://api.woosmap.com/localities/autocomplete/?input=london&key={PUBLIC_API_KEY}&types=locality&excluded_types=neighbourhood|quarter

To retrieve localities suggestions excluding quarters and neighbourhoods.

components

Geographic places to which you would like to restrict your results. Currently, you can use components to filter over countries. Countries are identified by a two character, ISO 3166-1 Alpha-2 or a three character, ISO 3166-1 Alpha-3 compatible country code. Multiple countries must be passed as distinct components, with the pipe character (|) as a separator.

To ensure best possible suggestions, you must specify countries you want results for. Doing so you’ll benefit from more up to date and accurate data Woosmap is sourcing from dedicated third parties providers.

Example

components=country:fr or components=country:fra would restrict your results to places within France. components=country:fr-fr returns locations only in Metropolitan France.

Multiple countries example

components=country:gb|country:fr|country:be|country:sp|country:it would restrict your results to Great Britain, France, Belgium, Spain and Italy.

See coverage for more details on the countries covered by Localities

language

The language code, indicating in which language the results should be returned, if possible. If no language parameter is supplied, first Accept-Language of the browser will be used. If neither the provided language or the Accept-Language are known, the Localities service uses the international default language (English). No language is necessary for a postal_code request. According to requested language, only parts of the address components might be translated.

location

This parameter is used to add a bias to the autocomplete feature. The location defines the point around which to retrieve results in priority. It must be specified in the latitude,longitude string format.

radius

This parameter may be used in addition to the location parameter to define the distance in meters within which the API will return results in priority. Results outside of the defined area may still be displayed. Default radius if this parameter is not set is 100 000.

data

This parameter accepts two values: standard (default) or advanced. The advanced value opens suggestions to worldwide postal codes in addition to postal codes for Western Europe. See details in the Localities API Coverage web page

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

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}, [...]"

Warning - If one field of the custom description is undefined, then the default description will be returned.

Available fields
  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 • • •   •   •  
Example
        custom_description=locality:"{name} - {administrative_area_level_0}"|postal_code:"{name} ({administrative_area_level_1})"

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

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

extended

This parameter accepts one value: postal_code. If set, this parameter allows a refined search over locality names that bears the same postal code. By triggering this parameter, integrators will benefit from a search spectrum on the locality type that includes postal codes. To avoid confusion, it is recommended not to activate this parameter along with the postal_code type which could lead to duplicate locations. Also, the default description returned by the API changes to name (postal code), admin_1, admin_0. This behavior is only available for France, Monaco, Italy, Spain, Belgium and Switzerland.

Localities Autocomplete example

A request for autocomplete containing the string “Lond” within the Great Britain (country “GB”):

Localities Autocomplete call
        https://api.woosmap.com/localities/autocomplete/
  ?components=country%3Agb
  &input=Lond
  &no_deprecated_fields=true
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    
        const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

    
        const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


    
        import requests

url = "https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY"

payload = {}
headers = {
    'Referer': 'http://localhost'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)


    
        OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY")
  .method("GET", body)
  .addHeader("Referer", "http://localhost")
  .build();
Response response = client.newCall(request).execute();

    
        require "uri"
require "net/http"

url = URI("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Referer"] = "http://localhost"

response = https.request(request)
puts response.read_body

Response

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 Autocomplete Collection Response
JSON
        {
  "localities":
    [
      {
        "public_id": "Ch6qA8cLmvyvEEoFy6nYeFcEdNU=",
        "type": "locality",
        "description": "London, City of London, United Kingdom",
        "matched_substrings":
          {
            "description":
              [{ "offset": 0, "length": 4 }, { "offset": 16, "length": 4 }],
          },
      },
      {
        "public_id": "m/T2C4YI2LgszkKXrELBC+9dfC8=",
        "type": "locality",
        "description": "Derry/Londonderry, Derry City and Strabane, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 6, "length": 4 }] },
      },
      {
        "public_id": "J6eISGMjjvQwPkao8rsByB3aVwM=",
        "type": "locality",
        "description": "London Colney, Hertfordshire, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 0, "length": 4 }] },
      },
      {
        "public_id": "52MnrbHVWH21CLWH8VY/YWKhqeM=",
        "type": "locality",
        "description": "London Apprentice, Cornwall, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 0, "length": 4 }] },
      },
      {
        "public_id": "Js0mQmmeI46X3hiqRj/R4pvb8mQ=",
        "type": "locality",
        "description": "Long Stratton, Norfolk, United Kingdom",
      },
    ],
}

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 varies 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.

On the specific territories of France and Italy, Localities Autocomplete returns a related field that contains a list of postal codes for a locality. For each postal code, a public_id and a description are returned. Then it is possible to fetch more detail about each postal code by requesting the Details endpoint with the postal code public_id.

Below, the content of the related object for the city of Strasbourg (France):

JSON
        "related": {
    "postal_codes": [
        {
            "public_id": "8yWv6KjsafWjcMSm64/6MI9h8vo=",
            "description": "67000, Strasbourg, France"
        },
        {
            "public_id": "YByyB1s6RmrbbLZmeOhQ27Y3DjQ=",
            "description": "67100, Strasbourg, France"
        },
        {
            "public_id": "FYUwPhuFZRgXcTIseIIa+EL1UYs=",
            "description": "67200, Strasbourg, France"
        }
    ]
}

As it is possible to do with the main locality description (with custom_description param), it is also possible to customize the description of related postal codes.

has_addresses

On the specific territory of United Kingdom, Localities Autocomplete request can return the has_addresses attribute for a postal code, which indicates if a postal code bears addresses. When has_addresses is true, it is possible to display a list of the available addresses by requesting the Details endpoint with the Localities public_id. To get the details of an address you need to request the Details endpoint once more passing in the dedicated address public_id.

Samples

Following are two samples showcasing the autocomplete requests.

Autocomplete on locality and postal code types only

Autocomplete on locality, postal code and address types in UK, FR, IT, SP and DE

Usage limits

The following usage limits are in place for the Localities API on the autocomplete and details endpoint combined:

‹ Get Started Details ›
Was this article helpful?
Have more questions? Submit a request