Source: https://developers.woosmap.com/api-reference/localities-api/get-localities-details/ > For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://developers.woosmap.com/llms.txt # Details of a Locality # 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`](#authorization-woosmap-platform-api-reference-publicapikeyauth) apiKeyquery A Public key generated specifically to authenticate API requests on the front side. See how to [register a Public API Key](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-public-api-key). [`Referer`](#authorization-woosmap-platform-api-reference-refererheader) apiKeyheader 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`](#authorization-woosmap-platform-api-reference-privateapikeyauth) apiKeyquery 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](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key). [`X-Api-Key`](#authorization-woosmap-platform-api-reference-privateapikeyheaderauth) apiKeyheader 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](https://developers.woosmap.com/api-reference/authentication/#registering-a-woosmap-private-api-key). ### Query Parameters [`public_id`](#query-public-id) stringrequired A textual identifier that uniquely identifies a locality, returned from a [Localities Autocomplete](https://developers.woosmap.com/products/localities/autocomplete/). Example:`MkvnYy6K6oVGqeqfWJGO/6eCgqo=` [`language`](#query-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`](#query-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`](#query-cc-format) string To specify the format for the short [country code](https://en.wikipedia.org/wiki/ISO_3166-1) 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`](#query-page) integerdeprecated 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`](#query-addresses-per-page) integerdeprecated 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 200application/json Details Localities successfully retrieved [`result`](#resp-200-result) object The Root Node for Localities Details #Show 9 propertiesHide 9 properties result.[`public_id`](#resp-200-result-public-id) stringrequired Contains a unique ID for each suggestion. Please use this ID to give feedbacks on results. Example:`MkvnYy6K6oVGqeqfWJGO/6eCgqo=` result.[`formatted_address`](#resp-200-result-formatted-address) stringrequired Contains the readable text description of the result. Example:`London, England, United Kingdom` result.[`types`](#resp-200-result-types) string[]required available localities types result.[`geometry`](#resp-200-result-geometry) objectrequired The location of the PostalCode, in latitude and longitude, eventually associated with a Viewport and a shape. Example: ```json { "location": { "lat": 51.49984, "lng": -0.124663 } } ``` Show 4 propertiesHide 4 properties result.geometry.[`location`](#resp-200-result-geometry-location) objectrequired An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties result.geometry.location.[`lat`](#resp-200-result-geometry-location-lat) numberrequired Latitude in decimal degrees Example:`42.3` result.geometry.location.[`lng`](#resp-200-result-geometry-location-lng) numberrequired Longitude in decimal degrees Example:`3.46` result.geometry.[`viewport`](#resp-200-result-geometry-viewport) object A rectangle in geographical coordinates from points at the southwest and northeast corners. Example: ```json { "northeast": { "lat": 49.315678, "lng": 4.15292 }, "southwest": { "lat": 49.31073, "lng": 4.145162 } } ``` Show 2 propertiesHide 2 properties result.geometry.viewport.[`northeast`](#resp-200-result-geometry-viewport-northeast) object An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties result.geometry.viewport.northeast.[`lat`](#resp-200-result-geometry-viewport-northeast-lat) numberrequired Latitude in decimal degrees Example:`42.3` result.geometry.viewport.northeast.[`lng`](#resp-200-result-geometry-viewport-northeast-lng) numberrequired Longitude in decimal degrees Example:`3.46` result.geometry.viewport.[`southwest`](#resp-200-result-geometry-viewport-southwest) object An object describing a specific location with Latitude and Longitude in decimal degrees. Example: ```json { "lat": 43.3, "lng": 3.46 } ``` Show 2 propertiesHide 2 properties result.geometry.viewport.southwest.[`lat`](#resp-200-result-geometry-viewport-southwest-lat) numberrequired Latitude in decimal degrees Example:`42.3` result.geometry.viewport.southwest.[`lng`](#resp-200-result-geometry-viewport-southwest-lng) numberrequired Longitude in decimal degrees Example:`3.46` result.geometry.[`shape`](#resp-200-result-geometry-shape) object A GeoJSon Geometry representing the shape of the area, as specified in [RFC7946](https://datatracker.ietf.org/doc/html/rfc7946). To display on the map, simply wrap this object in a feature: ``` { "type": "Feature", "geometry": this_geojson_geometry } ``` Example: ```json { "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`](#resp-200-result-geometry-shape-type) string the geometry type Available options:`Polygon`, `MultiPoligon` result.geometry.shape.[`coordinates`](#resp-200-result-geometry-shape-coordinates) array[] result.geometry.[`accuracy`](#resp-200-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`](#resp-200-result-address-components) object[]required An array containing Address Components with additional information Example: ```json [ { "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`](#resp-200-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`](#resp-200-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`](#resp-200-result-address-components-types) string[] An array indicating the type of the address component. Example: ```json [ "country", "administrative_area_level_0" ] ``` result.[`name`](#resp-200-result-name) string The postal code name if result is a postal code. Example:`SW1A 0AA` result.[`administrative_area_label`](#resp-200-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`](#resp-200-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`](#resp-200-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`](#resp-200-result-addresses-pagination) objectdeprecated 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`](#resp-200-result-addresses-pagination-page) integerdeprecated the request page result.addresses.pagination.[`page_count`](#resp-200-result-addresses-pagination-page-count) integerdeprecated the number of available pages result.addresses.pagination.[`addresses_per_page`](#resp-200-result-addresses-pagination-addresses-per-page) integerdeprecated the number of available addresses per page result.addresses.pagination.[`address_count`](#resp-200-result-addresses-pagination-address-count) integerdeprecated the number of available addresses result.addresses.[`list`](#resp-200-result-addresses-list) object[] List of addresses Show 2 propertiesHide 2 properties result.addresses.list.[`public_id`](#resp-200-result-addresses-list-public-id) stringrequired The public\_id of the address can be used to gather details on that specific address Example:`Nmp0K1VVUFQ4eFI3S1BuaDZEZVVJVWhYY3A4PV9faitia1pNNURnOWYvQmRjMUdweXl5SjdLZUZnPQ==` result.addresses.list.[`description`](#resp-200-result-addresses-list-description) stringrequired 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`](#err-401-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`](#err-403-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`](#err-429-detail) string Details for the Over Query Limit error message Example:`The rate limit for this endpoint has been exceeded` ```shell curl -L 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY' \ -H 'Referer: http://localhost' ``` ```javascript 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)); ``` ```python 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) ``` ```json-200-address { "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" } ] } } ``` ```json-200-postalcode { "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" } ] } } } ``` ```json { "detail": "Incorrect authentication credentials. Please check or use a valid API Key" } ``` ```json { "detail": "This Woosmap API is not enabled for this project." } ``` ```json { "detail": "The rate limit for this endpoint has been exceeded" } ```