Get Details for an Autocomplete Suggestion

Get detailed information about an autocomplete suggestion

  1. Overview
  2. Required Parameters
  3. Optional Parameters
  4. Localities Details example
  5. Responses
  6. Usage limits
  7. Samples

Overview

Woosmap Localities details endpoint provides details for an autocomplete suggestion (using the suggestion’s public_id).

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

http
        https://api.woosmap.com/localities/details?key={PUBLIC_API_KEY}&public_id={LOCALITES_PUBLIC_ID}

    

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

The Details endpoint of Localities API is subject to a specific pricing. Request costs vary according to the data you request details for. Visit our pricing page or get in touch with your Customer Care contact to learn how to estimate you license accordingly.

Required Parameters

Certain parameters are required to initiate a Details request. As is standard in URLs, all parameters are separated using the ampersand(&) character. Few parameters are mandatory like the public_id which must be present in addition to a Woosmap API key.

http
        https://api.woosmap.com/localities/details?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&key={PUBLIC_API_KEY}

    

public_id

The identifier of the autocomplete suggestion. (public_id can be retrieved in the Autocomplete response).

key

Your project’s API key. This key identifies your Woosmap Project for security and quota management purposes. Public keys are designed to be used client side, where every request contain a referer. Alternatively, you can use the parameter private_key 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) where 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, no referer checking associated with those keys.

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

Optional Parameters

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). Depending on requested language, only parts of the address components might be translated.

fields

You can use this parameter to limit the fields returned in the response. This parameter can be any combination of geometry, address_components or shape (defaults to geometry|address_components). If set, it will limit the content of responses to the specified fields. For example, fields=geometry will limit the response to the geometry part and you won’t get the address_components, which can help with cost optimization in certain countries. fields=shape will include the shape for most provided types except addresses: country, admin_level, postal_code and locality.

cc_format

To specify the country code format returned in the response. Default is alpha2.

Available cc_format values are alpha2 or alpha3.

page

In a few cases, a postal code details may contain addresses (UK postal codes). The address list is paginated. In that case, you can navigate in the address list thanks to the page and addresses_per_page parameters.

Notice: as all the addresses are now automatically returned in the response, the page parameter is deprecated and has been turned off on December 31, 2021.

addresses_per_page

In a few cases, a postal code details may contain addresses (UK postal codes). The address list is paginated. In that case, you can navigate in the address list thanks to the addresses_per_page and page parameters.

Notice: as all the addresses are now automatically returned in the response, the addresses_per_page parameter is deprecated and has been turned off on December 31, 2021.

Localities Details example

The following example requests the details of a locality by specifying the required public_id:

Localities Details call
        https://api.woosmap.com/localities/details
  ?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D
  &key=YOUR_PUBLIC_API_KEY
    
        curl -L -X GET 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    
        var requestOptions = {
  method: 'GET',
  redirect: 'follow'
};

fetch("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

    
        var axios = require('axios');

var config = {
  method: 'get',
  url: 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY',
  headers: { 
    'Referer': 'http://localhost'
  }
};

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


    
        import requests

url = "https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&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/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&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/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&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


    

Responses

To retrieve detailed data, including geometry and address_components, a Details request must be performed passing in the public_id of the selected address.

Localities Details API endpoint provides a JSON response containing one root element, result which contains the serialized address result.

A result contains the following fields:

public_id

The public_id of the result (return by the Autocomplete response)

formatted_address

Contains the text description of the proposal to be used as suggestion in a drop-down list if needed.

types

Contains the type of the result. See the list of existing types

administrative_area_label

This field is only available for admin_level suggestions. It provides the local english name of the administration level (“department” for France or “federal_state” for Germany).

geometry

The location of the result, in latitude and longitude, as well as its viewport when applicable and its shape when requested. Accuracy is also provided when appropriate (mostly for addresses). When provided, accuracy values can be ROOFTOP, POSTAl_CODE or DISTRICT. If POSTAl_CODE or DISTRICT accuracy are provided, be aware that location accuarcy may not be suitable for some use cases.

address_components

Detailed fields of the result (long and short). Available fields 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 route street_number premise organisation post_box
address    
locality IT and FR only              
postal_code                  
admin_level                      
country                        
airport                    
train_station                
metro_station                
shopping                
museum                
tourist_attraction                
amusement_park                
art_gallery                
zoo                

addresses

This field is only available for UK postal codes that bear addresses. It contains an array of addresses, with their description and public_id. The address details can be retrieved passing the public_id to the /details endpoint. The address list is paginated and you can find the following structure in the response to know where you are in the list.

        "pagination": {
    "page": 1,
    "page_count": 1,
    "addresses_per_page": 19,
    "address_count": 19
},

    

The pagination part of the response is deprecated as all the addresses are now automatically returned in the response. It will be turned off at some point. From now on, the pagination will systematically return page=1, pages_count=1, addresses_per_page=[total addresses count] and address_count=[total addresses count].

status

This optional field is only specified for UK not yet built addresses.

Only one value yet, not_yet_built for addresses referenced as not yet built addresses by Royal Mail.

Example of a UK postal code details (with addresses)

Localities Details Postal Code Response
JSON
        {
  "result":
    {
      "public_id": "QaCU+fBtigK65ztSrqHqUoUDwZw=",
      "types": ["postal_code"],
      "formatted_address": "SW1A 0AA, City of London",
      "geometry": { "location": { "lat": 51.49984, "lng": -0.124663 } },
      "name": "SW1A 0AA",
      "address_components":
        [
          {
            "short_name": "GB",
            "long_name": "United Kingdom",
            "types": ["country", "administrative_area_level_0"],
          },
          {
            "short_name": "City of London",
            "long_name": "City of London",
            "types": ["administrative_area_level_1"],
          },
        ],
      "addresses":
        {
          "pagination":
            {
              "page": 1,
              "page_count": 1,
              "addresses_per_page": 1,
              "address_count": 1,
            },
          "list":
            [
              {
                "public_id": "TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ==",
                "description": "House Of Commons, Houses Of Parliament, London, SW1A 0AA",
              },
            ],
        },
    },
}

    

Example of an address details

Localities Details Address Response
JSON
        {
  "result":
    {
      "public_id": "TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ==",
      "types": ["address"],
      "formatted_address": "House Of Commons, Houses Of Parliament, London, SW1A 0AA",
      "geometry":
        {
          "location": { "lat": 51.4998415, "lng": -0.1246375 },
          "accuracy": "ROOFTOP",
        },
      "address_components":
        [
          {
            "short_name": "GB",
            "long_name": "United Kingdom",
            "types": ["country", "administrative_area_level_0"],
          },
          {
            "short_name": "City of London",
            "long_name": "City of London",
            "types": ["administrative_area_level_1"],
          },
          {
            "short_name": "City of London",
            "long_name": "City of London",
            "types": ["county"],
          },
          {
            "short_name": "London SW",
            "long_name": "London SW",
            "types": ["district"],
          },
          {
            "short_name": "London",
            "long_name": "London",
            "types": ["locality"],
          },
          {
            "short_name": "SW1A 0AA",
            "long_name": "SW1A 0AA",
            "types": ["postal_codes"],
          },
          {
            "short_name": "Houses Of Parliament",
            "long_name": "Houses Of Parliament",
            "types": ["premise"],
          },
          {
            "short_name": "House Of Commons",
            "long_name": "House Of Commons",
            "types": ["organisation"],
          },
        ],
    },
}

    

Usage limits

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

Samples

Get details on address and localities

Get details on Postal Codes with addresses (only available in the UK).

Get details with fields=shape parameter

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