Details of a Locality

GET

https://api.woosmap.com/localities/details

Provides details of an autocomplete suggestion (using the suggestion’s public_id).

Authorization

key

apiKey query

A Public key generated specifically to authenticate API requests on the front side. See how to register a Public API Key.

Referer

apiKey header

The Referer HTTP request header is mandatory when using PublicApiKeyAuth. In browser environment, the Referer is set by the browser itself and cannot be overridden.

private_key

apiKey query

A Private key generated specifically to authenticate API requests on server side. Required for Data management API. See how to register a Private API Key.

X-Api-Key

apiKey header

A Private key to authenticate API requests through the Header instead of Query parameter. Use either PrivateApiKeyHeaderAuth or PrivateApiKeyAuth. See how to register a Private API Key.

Query Parameters

public_id

string required

A textual identifier that uniquely identifies a locality, returned from a Localities Autocomplete.

Example: MkvnYy6K6oVGqeqfWJGO/6eCgqo=

language

string

The language code, using ISO 639-2 Alpha-2 country codes, indicating in which language the results should be returned, if possible. If language is not 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.

Example: en

fields

string

If set, it will limit the content of responses to the specified fields. This parameter can be any combination of geometry, address_components or shape (defaults to geometry|address_components).

Available options: geometry

Example: geometry

cc_format

string

To specify the format for the short country code expected to be returned in the address_components field. Default is the format used to specify components or alpha2 if no components are specified.

Available options: alpha2, alpha3

Example: alpha2

page

integer deprecated

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 page parameter is deprecated and has been turned off on December 31, 2021.

Example: 1

addresses_per_page

integer deprecated

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.

Example: 10

Response

200 application/json

Details Localities successfully retrieved

result

object

The Root Node for Localities Details

Show 9 propertiesHide 9 properties

result. public_id

string required

Contains a unique ID for each suggestion. Please use this ID to give feedbacks on results.

Example: MkvnYy6K6oVGqeqfWJGO/6eCgqo=

result. formatted_address

string required

Contains the readable text description of the result.

Example: London, England, United Kingdom

result. types

string[] required

available localities types

result. geometry

object required

The location of the PostalCode, in latitude and longitude, eventually associated with a Viewport and a shape.

Example:

        {
  "location": {
    "lat": 51.49984,
    "lng": -0.124663
  }
}

Show 4 propertiesHide 4 properties

result.geometry. location

object required

An object describing a specific location with Latitude and Longitude in decimal degrees.

Example:

        {
  "lat": 43.3,
  "lng": 3.46
}

Show 2 propertiesHide 2 properties

result.geometry.location. lat

number required

Latitude in decimal degrees

Example: 42.3

result.geometry.location. lng

number required

Longitude in decimal degrees

Example: 3.46

result.geometry. viewport

object

A rectangle in geographical coordinates from points at the southwest and northeast corners.

Example:

        {
  "northeast": {
    "lat": 49.315678,
    "lng": 4.15292
  },
  "southwest": {
    "lat": 49.31073,
    "lng": 4.145162
  }
}

Show 2 propertiesHide 2 properties

result.geometry.viewport. northeast

object

An object describing a specific location with Latitude and Longitude in decimal degrees.

Example:

        {
  "lat": 43.3,
  "lng": 3.46
}

Show 2 propertiesHide 2 properties

result.geometry.viewport.northeast. lat

number required

Latitude in decimal degrees

Example: 42.3

result.geometry.viewport.northeast. lng

number required

Longitude in decimal degrees

Example: 3.46

result.geometry.viewport. southwest

object

An object describing a specific location with Latitude and Longitude in decimal degrees.

Example:

        {
  "lat": 43.3,
  "lng": 3.46
}

Show 2 propertiesHide 2 properties

result.geometry.viewport.southwest. lat

number required

Latitude in decimal degrees

Example: 42.3

result.geometry.viewport.southwest. lng

number required

Longitude in decimal degrees

Example: 3.46

result.geometry. shape

object

A GeoJSon Geometry representing the shape of the area, as specified in RFC7946. To display on the map, simply wrap this object in a feature:

{
  "type": "Feature",
  "geometry": this_geojson_geometry
}

Example:

        {
  "type": "Polygon",
  "coordinates": [
    [
      [
        2.06984,
        48.77919
      ],
      [
        2.07984,
        48.77919
      ],
      [
        2.07984,
        48.78919
      ],
      [
        2.06984,
        48.78919
      ],
      [
        2.06984,
        48.77919
      ]
    ]
  ]
}

Show 2 propertiesHide 2 properties

result.geometry.shape. type

string

the geometry type

Available options: Polygon, MultiPoligon

result.geometry.shape. coordinates

array[]

result.geometry. accuracy

string

This accuracy represents the type of address returned - DISTRICT and POSTAL_CODE are for UK only.

Show 7 enum values Hide 7 enum values

ROOFTOP

ROUTE

GEOMETRIC_CENTER

DISTRICT

POSTAL_CODE

RANGE_INTERPOLATED

APPROXIMATE

result. address_components

object[] required

An array containing Address Components with additional information

Example:

        [
  {
    "types": [
      "country"
    ],
    "long_name": "United Kingdom",
    "short_name": "GBR"
  },
  {
    "long_name": "London",
    "short_name": "London",
    "types": [
      "locality"
    ]
  }
]

Show 3 propertiesHide 3 properties

result.address_components. long_name

string | array

The full text description or name of the address component, or a list of names (ie. list of postal codes).

Example: United Kingdom

result.address_components. short_name

string | array

An abbreviated textual name for the address component, if available. For example, an address component for the state of United Kingdom may have a long_name of United Kingdom and a short_name of UK using the 2-letter postal abbreviation.

Example: UK

result.address_components. types

string[]

An array indicating the type of the address component.

Example:

        [
  "country",
  "administrative_area_level_0"
]

result. name

string

The postal code name if result is a postal code.

Example: SW1A 0AA

result. administrative_area_label

string

Only available for admin_level suggestions, this contains the local english name of the administration level ("department" for France or "federal_state" for Germany).

Example: district

result. status

string

This optional field is only available for UK addresses referenced as not yey built by Royal Mail. Only one value yet.

Available options: not_yet_built

result. addresses

object

For the UK only. When a postal code is returned, this field contains a list of addresses associated with this postal code.

Show 2 propertiesHide 2 properties

result.addresses. pagination

object deprecated

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.

Show 4 propertiesHide 4 properties

result.addresses.pagination. page

integer deprecated

the request page

result.addresses.pagination. page_count

integer deprecated

the number of available pages

result.addresses.pagination. addresses_per_page

integer deprecated

the number of available addresses per page

result.addresses.pagination. address_count

integer deprecated

the number of available addresses

result.addresses. list

object[]

List of addresses

Show 2 propertiesHide 2 properties

result.addresses.list. public_id

string required

The public_id of the address can be used to gather details on that specific address

Example: Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9faitia1pNNURnOWYvQmRjMUdweXl5SjdLZUZnPQ==

result.addresses.list. description

string required

A human readable description of the address

Example: Flat 1, Radway House, Alfred Road, London, W2 5ER

Errors

401

Unauthorized. Incorrect authentication credentials.

application/json

detail

string

Details for the credentials error

Example: Incorrect authentication credentials. Please check or use a valid API Key

403

Forbidden. This Woosmap API is not enabled for this project.

application/json

detail

string

Details for the forbidden error message

Example: This Woosmap API is not enabled for this project.

429

Too Many Requests. The rate limit for this endpoint has been exceeded.

application/json

detail

string

Details for the Over Query Limit error message

Example: The rate limit for this endpoint has been exceeded

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

            const 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.error(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)

            {
  "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": [
      {
        "types": [
          "country",
          "administrative_area_level_0",
          "division_level_0"
        ],
        "long_name": "United Kingdom",
        "short_name": "GB"
      },
      {
        "types": [
          "state",
          "division_level_1"
        ],
        "long_name": "England",
        "short_name": "England"
      },
      {
        "types": [
          "administrative_area_level_1",
          "county",
          "division_level_2"
        ],
        "long_name": "City of London",
        "short_name": "City of London"
      },
      {
        "types": [
          "district",
          "division_level_3"
        ],
        "long_name": "Westminster",
        "short_name": "Westminster"
      },
      {
        "types": [
          "locality"
        ],
        "long_name": "London",
        "short_name": "London"
      },
      {
        "types": [
          "postal_codes"
        ],
        "long_name": "SW1A 0AA",
        "short_name": "SW1A 0AA"
      },
      {
        "types": [
          "premise"
        ],
        "long_name": "Houses Of Parliament",
        "short_name": "Houses Of Parliament"
      },
      {
        "types": [
          "organisation"
        ],
        "long_name": "House Of Commons",
        "short_name": "House Of Commons"
      }
    ]
  }
}

    

            {
  "result": {
    "public_id": "QaCU+fBtigK65ztSrqHqUoUDwZw=",
    "types": [
      "postal_code"
    ],
    "formatted_address": "SW1A 0AA, City of London",
    "name": "SW1A 0AA",
    "geometry": {
      "location": {
        "lat": 51.499842,
        "lng": -0.124638
      },
      "accuracy": "GEOMETRIC_CENTER"
    },
    "address_components": [
      {
        "types": [
          "country",
          "administrative_area_level_0",
          "division_level_0"
        ],
        "long_name": "United Kingdom",
        "short_name": "GB"
      },
      {
        "types": [
          "state",
          "division_level_1"
        ],
        "long_name": "England",
        "short_name": "England"
      },
      {
        "types": [
          "administrative_area_level_1",
          "county",
          "division_level_2"
        ],
        "long_name": "City of London",
        "short_name": "City of London"
      },
      {
        "types": [
          "district",
          "division_level_3"
        ],
        "long_name": "Westminster",
        "short_name": "Westminster"
      },
      {
        "types": [
          "postal_codes"
        ],
        "long_name": "SW1A 0AA",
        "short_name": "SW1A 0AA"
      }
    ],
    "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"
        }
      ]
    }
  }
}

    

            {
  "detail": "Incorrect authentication credentials. Please check or use a valid API Key"
}

    

            {
  "detail": "This Woosmap API is not enabled for this project."
}

    

            {
  "detail": "The rate limit for this endpoint has been exceeded"
}

    