Get Details for an Autocomplete Suggestion

How to build your Localities API Details requests

  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Address Details Response
  5. Postal Code Details Response
  6. Samples

Introduction

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.

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}

On the specific territory of United Kingdom, Localities autocomplete request can return the additional attribute has_addresses 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 details with the Localities public_id. To get the details of an address you will need to request again /details endpoint passing in the dedicated address public_id.

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 contains a referer.

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.

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.

Optional Parameters

fields

You can use this parameter to limit the returning fields (by default, all fields are return).

Available fields are (geometry) (fields should be separated by a ,). By using this parameter you will limit content of responses to the geometry part. No address component will be returned.

Address Details Response

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

It is possible to narrow down the response of the API to only geographic coordinates, stripping away the address_components by adding the parameter fields=geometry.

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

The API responses contains attributes as follows:

{
  "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"
      }
    ]
  }
}

result

A result contains the following fields:

formatted_address

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

types

Contains the type of result. Value is address.

public_id

The public_id of the result (return by the Autocomplete response

geometry

The location of the result, in latitude and logitude. Accuracy is also provided.

Postal Code Details Response

Only available on UK territory.

https://api.woosmap.com/localities/details?key={PUBLIC_API_KEY}&public_id=QaCU+fBtigK65ztSrqHqUoUDw

Localities Details provides a JSON response containing one root element, result which contains an array of addresses, with the associated description contained into the postal code. The address list is paginated.

{
  "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="
        }
      ]
    }
  }
}

result

A result contains the following fields:

formatted_address

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

types

Contains the type of result. Value is postal_code.

public_id

The public_id of the result (return by the Autocomplete response

address_components

Description of all the components of the address (long and short). Those fields are provided when no fields parameter is set in the request.

geometry

The location of the result, in latitude and logitude.

Samples

Following are two samples showcasing the autocomplete and details requests to return address suggestions, or a list of addresses beared by a postal code (only available in the UK).

Address autocomplete and Lookup

Address list on Postal Code autocomplete

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