Get Details for an Autocomplete Suggestion

Get detailed information about an autocomplete suggestion

  1. Overview
  2. Required Parameters
  3. Optional Parameters
  4. Response
  5. Usage limits
  6. Samples

Overview

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

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

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 which is different from an autocomplete request. 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.

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 purposes of security and quota management. 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

fields

You can use this parameter to limit the fields returned in the response (by default, all fields are returned). This parameter accepts one value: geometry. 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.

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

Response

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

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

geometry

The location of the result, in latitude and longitude. Accuracy is also provided when appropriate (mostly for addresses).

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

Example of a UK postal code details (with addresses)

{
  "result": {
    "formatted_address": "SW1A 0AA, City of London",
    "types": [
      "postal_code"
    ],
    "public_id": "QaCU+fBtigK65ztSrqHqUoUDwZw=",
    "name": "SW1A 0AA",
    "geometry": {
      "location": {
        "lat": 51.49984,
        "lng": -0.124663
      }
    },
    "address_components": [
      {
        "types": [
          "country",
          "administrative_area_level_0"
        ],
        "long_name": "United Kingdom",
        "short_name": "GB"
      },
      {
        "types": [
          "administrative_area_level_1"
        ],
        "long_name": "City of London",
        "short_name": "City of London"
      }
    ],
    "addresses": {
      "pagination": {
        "page": 1,
        "page_count": 1,
        "addresses_per_page": 20,
        "address_count": 5
      },
      "list": [
        {
          "description": "Postmasters Redirection Service, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
          "public_id": "DuxKg3/i5t1AuSt1qvwaiSgd+gI="
        },
        {
          "description": "The Speakers House, 1 Parliament Square, London, SW1A 0AA",
          "public_id": "J9y6c0VHd8L5djgVKAmUZir1D74="
        },
        {
          "description": "Speakers Housekeepers Apartment, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
          "public_id": "K13iP+XIfYK2h+6NFqVVX2q0NQ8="
        },
        {
          "description": "House Of Commons, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
          "public_id": "MVZWBfGZQnAQn9JtE9CJZjgeB4Q="
        },
        {
          "description": "Lord Chancellors Residence, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
          "public_id": "i5WqCPd+qTTnZtiXnKzV8KoIpT8="
        }
      ]
    }
  }
}

Example of an address details

{
  "result": {
    "formatted_address": "House Of Commons, House Of Commons Palace Of Westminster, Parliament Square, London, SW1A 0AA",
    "types": [
      "address"
    ],
    "public_id": "MVZWBfGZQnAQn9JtE9CJZjgeB4Q=",
    "geometry": {
      "location": {
        "lat": 51.49984,
        "lng": -0.1246375
      },
      "accuracy": "ROOFTOP"
    },
    "address_components": [
      {
        "types": [
          "country",
          "administrative_area_level_0"
        ],
        "long_name": "United Kingdom",
        "short_name": "GB"
      },
      {
        "types": [
          "administrative_area_level_1"
        ],
        "long_name": "City of London",
        "short_name": "City of London"
      },
      {
        "types": [
          "premise"
        ],
        "long_name": "House Of Commons Palace Of Westminster",
        "short_name": "House Of Commons Palace Of Westminster"
      },
      {
        "types": [
          "locality"
        ],
        "long_name": "London",
        "short_name": "London"
      },
      {
        "types": [
          "postal_codes"
        ],
        "long_name": "SW1A 0AA",
        "short_name": "SW1A 0AA"
      },
      {
        "types": [
          "organisation"
        ],
        "long_name": "House Of Commons",
        "short_name": "House Of Commons"
      },
      {
        "types": [
          "route"
        ],
        "long_name": "Parliament Square",
        "short_name": "Parliament Square"
      }
    ]
  }
}

Usage limits

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

Samples

Address autocomplete and Lookup

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

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