Details

Get details of an autocomplete suggestion

  1. Introduction
  2. Required Parameters
  3. Optional Parameters
  4. Responses
  5. Usage limits

Introduction

Woosmap Address Details endpoint provides details of an autocomplete suggestion (using the suggestion public_id).

A Woosmap Address Details request is an HTTP URL of the following form:

https://api.woosmap.com/address/details/json?parameters

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/address/details/json?public_id=aGVyZTpjbTpuYW1lZHBsYWNlOjIwMDA1MTI2&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.

Reminder: To use the Address 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

language

The language to return the address elements in. Must be a ISO 639-1 language code.

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

cc_format

To specify the format for the short country code expected to be returned in the address_components field (default is alpha3).

Available cc_format are (alpha2, alpha3)

Responses

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

{
  "result": {
    "formatted_address": "Clamart, \u00cele-de-France, France",
    "types": [
      "locality"
    ],
    "public_id": "aGVyZTpjbTpuYW1lZHBsYWNlOjIwMDA1MTI2",
    "address_components": [
      {
        "types": [
          "country"
        ],
        "long_name": "France",
        "short_name": "FR"
      },
      {
        "long_name": "Clamart",
        "short_name": "Clamart",
        "types": [
          "locality"
        ]
      },
      {
        "long_name": "92140",
        "short_name": "92140",
        "types": [
          "postal_code"
        ]
      }
    ],
    "geometry": {
      "location_type": "GEOMETRIC_CENTER",
      "location": {
        "lat": 48.79988,
        "lng": 2.2631
      },
      "viewport": {
        "northeast": {
          "lat": 48.81702,
          "lng": 2.27998
        },
        "southwest": {
          "lat": 48.77443,
          "lng": 2.22366
        }
      }
    }
  },
  "status": "OK"
}

Result

A result contains the following fields:

formatted_address

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

type

Contains the type of result. Can be any value from following list:
house_number route address_block locality admin_level country

public_id

The public_id of the result (return by autocomplete endpoint)

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 geometry and the viewport of the result.

status

Returns more info on if the request was successful or not, valid responses:

OK indicates the response contains a valid result.
INVALID_REQUEST indicates that the provided request was invalid (e.g. wrong URL syntax).
REQUEST_DENIED indicates that the service denied use of the Address API (e.g. wrong API Key, wrong/no referer, …).
UNKNOWN_ERROR indicates an Address API request could not be processed due to a server error. The request may succeed if you try again.

Usage limits

The following usage limits are in place for the Address API on the /details endpoint:

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