Source: https://developers.woosmap.com/products/localities/features/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 # Localities Details **Complete API Specification** : [Details Endpoint Reference](/api-reference/localities-api/get-localities-details/) ## What is the Details Endpoint? The Details Endpoint converts a `public_id` (returned by [Localities Autocomplete](/products/localities/features/autocomplete/)) into complete location information. You call this endpoint after a user selects an autocomplete suggestion to get the full address with structured components, precise coordinates, and optional geographic shapes. ### What It Does Details returns everything you need about a selected location: formatted addresses, structured address components ( street, city, postal code, etc.), latitude/longitude coordinates with accuracy levels, and optional geographic boundaries. The response structure depends on the location type—addresses include street-level details, while postal codes may include lists of individual addresses (particularly in the UK and Ireland). ### Key Characteristics This is **not** a search—you must provide a valid `public_id` from an Autocomplete response. Response completeness and cost vary by location type and the `fields` parameter you specify. You can control exactly what data you receive to optimize both response size and billing. ## When to Use This Endpoint Use Details after a user selects an autocomplete suggestion. This is the required second step in the interactive address search workflow: Autocomplete → User Selection → Details → Store/Display Complete Address. Don’t use Details for bulk address processing—that’s what [Localities Geocoding](/products/localities/features/geocoding/) is for. And never skip calling Localities Details to save costs—using Autocomplete responses without fetching Details violates our [terms of service](https://www.woosmap.com/policies/terms/). Address and postal code details may require specific product activation. See [Address Coverage](/products/localities/concepts/address-coverage/) for details. Request costs vary by location type and requested fields. Visit the [pricing page](https://www.woosmap.com/en/pricing#localities_details) for billing details. New to the API? Start with the [Quickstart Tutorial](/products/localities/tutorials/making-first-request/) for the complete Autocomplete → Details workflow. ## API Endpoint ```http GET https://api.woosmap.com/localities/details ``` ### Authentication Authenticate using either a `key` (public API key for client-side requests) or `private_key` (for server-side requests). Public keys require domain/IP restrictions, while private keys should be kept secret and never exposed in client code. You can also use the `X-Api-Key` header for server-side or mobile authentication. ```shell # Client-side (query parameter) ?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&key=YOUR_PUBLIC_KEY # Server-side (query parameter) ?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&private_key=YOUR_PRIVATE_KEY # Server-side / Mobile (header) -H "X-Api-Key: YOUR_PRIVATE_KEY" ``` For complete authentication details and security best practices, see [API Keys Documentation](/api-reference/authentication/). ## Request Parameters ### Required Parameters **`public_id`** - The unique identifier from an [Autocomplete](/products/localities/features/autocomplete/) suggestion response. **`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above. ### Key Optional Parameters **`fields`** - Control what data you receive (default: `geometry|address_components`). Accepts any combination of `geometry`, `address_components`, or `shape`. Use this to optimize response size and billing—for example, `fields=geometry` returns only coordinates. **`language`** - Return results in a specific language where available (e.g., `fr`, `de`, `en`). ### Complete Parameter Reference For all available parameters, data types, and constraints, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-details/). ## Implementation Options Choose the best integration approach for your project. See the [Integration Path Guide](/products/localities/guides/integration-path/) for a detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options. ## Request Examples ### Basic Request ```shell curl "https://api.woosmap.com/localities/details/?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&key=YOUR_KEY" ``` ### Request with Limited Fields ```shell # Get only coordinates (cost optimization) curl "https://api.woosmap.com/localities/details/?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&fields=geometry&key=YOUR_KEY" ``` ### Request with Shape ```shell # Get geographic boundary curl "https://api.woosmap.com/localities/details/?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&fields=geometry,shape&key=YOUR_KEY" ``` ### Multi-Language Examples ```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)); ``` ```shell curl -L 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY' \ -H 'Referer: http://localhost' ``` ```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) ``` ```text https://api.woosmap.com/localities/details ?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D &key=YOUR_PUBLIC_API_KEY ``` ```javascript const axios = require('axios'); let config = { method: 'get', maxBodyLength: Infinity, url: 'https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY', headers: { 'Referer': 'http://localhost' } }; axios.request(config) .then((response) => { console.log(JSON.stringify(response.data)); }) .catch((error) => { console.log(error); }); ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("text/plain"); RequestBody body = RequestBody.create(mediaType, ""); Request request = new Request.Builder() .url("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY") .method("GET", body) .addHeader("Referer", "http://localhost") .build(); Response response = client.newCall(request).execute(); ``` ```ruby require "uri" require "net/http" url = URI("https://api.woosmap.com/localities/details?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D&key=YOUR_PUBLIC_API_KEY") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Get.new(url) request["Referer"] = "http://localhost" response = https.request(request) puts response.read_body ``` ## Understanding the Response Localities Details returns complete information about the selected location. For the complete response schema, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-details/). ### Key Response Fields **`public_id`** - The unique identifier (matches the request parameter) **`formatted_address`** - Human-readable complete address ```json "formatted_address": "10 Downing Street, London, SW1A 2AA, United Kingdom" ``` **`geometry`** - Coordinates and accuracy level ```json "geometry": { "location": {"lat": 51.50336, "lng": -0.12767}, "accuracy": "ROOFTOP" } ``` Accuracy values: `ROOFTOP` (most precise), `POSTAL_CODE`, or `DISTRICT` (less precise for some use cases). **`address_components`** - Structured address parts (street number, route, locality, postal code, country, etc.). Available fields vary by location type. **`types`** - The location category (e.g., `address`, `locality`, `postal_code`). See [Locality Types](/products/localities/concepts/locality-types/) for the complete list. ### Special Response Features **UK & IE Postal Codes with Addresses** - Some UK and Republic of Ireland postal codes include an `addresses` array containing `public_id` and `description` for each address. Call Details again with an address `public_id` to get street-level information. **France & Italy Postal Codes** - Related postal codes are returned directly in Autocomplete responses, not in Details. **Administrative Levels** - Include an `administrative_area_label` field with the local English name (e.g., “department” for France, “federal\_state” for Germany). **UK Not Yet Built Addresses** - Include a `status` field set to `not_yet_built` for addresses in construction. ### Address Component Availability Available fields depend on the location type. For the complete field availability matrix by type (address, locality, postal\_code, airport, etc.), see the [OpenAPI Specification](/api-reference/localities-api/get-localities-details/). ## Response Examples ```json { "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", }, ], }, } ``` ## Usage Limits & Quotas - **Rate Limit** : 50 queries per second (QPS) per project (combined Autocomplete + Details) - Exceeding limits returns `429 Too Many Requests` - Contact support for higher quotas ## Working Code Examples ### Example 1: Address and Locality Details See the complete [Localities API Details JS Sample](/js-samples/localities-api-details/) for implementation details. https://demo.woosmap.com/js-samples/samples/localities-api-details/app/dist/ [](https://demo.woosmap.com/js-samples/samples/localities-api-details/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-api-details/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-api-details/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-api-details) ### Example 2: UK Postal Codes with Addresses See the complete [Localities API Details (Postal Codes) JS Sample](/js-samples/localities-api-details-postalcodes/) for implementation details. https://demo.woosmap.com/js-samples/samples/localities-api-details-postalcodes/app/dist/ [](https://demo.woosmap.com/js-samples/samples/localities-api-details-postalcodes/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-api-details-postalcodes/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-api-details-postalcodes/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-api-details-postalcodes) ### Example 3: Geographic Shapes with `fields=shape` See the complete [Localities API Shape JS Sample](/js-samples/localities-api-shape/) for implementation details. https://demo.woosmap.com/js-samples/samples/localities-api-shape/app/dist/ [](https://demo.woosmap.com/js-samples/samples/localities-api-shape/highlight/highlight.html "Open in new tab with highlighted code") Try sample - [CodeSandbox](https://codesandbox.io/p/devbox/github/woosmap/js-samples/tree/master/dist/samples/localities-api-shape/app?file=index.ts) - [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-api-shape/jsfiddle) - [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-api-shape) ## Related Features **Required Integration:** - [Localities Autocomplete](/products/localities/features/autocomplete/) - **Required** to get `public_id` for Details requests **Alternative Solutions:** - [Localities Geocoding](/products/localities/features/geocoding/) - Convert complete addresses to coordinates without user interaction - [Localities Nearby](/products/localities/features/nearby/) - Find points of interest around a location