Community Forum

Localities Details API

Retrieve comprehensive details for any autocomplete suggestion using its public_id. This API provides full locality, address, and POI information for selected search results.
  1. What is the Details API?
  2. When to Use This API
  3. API Endpoint
  4. Request Parameters
  5. Implementation Options
  6. API Request Examples
  7. Understanding the Response
  8. Response Examples
  9. Usage Limits & Quotas
  10. Working Code Examples
  11. Related Features

Complete API Specification: Details API Reference

What is the Details API?

The Details API converts a public_id (returned by the Autocomplete API) 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).

Key Characteristics

This is not a search API—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 API

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 Geocoding is for. And never skip calling Details to save costs—using Autocomplete responses without fetching Details violates terms of service.

Address and postal code details may require specific product activation. See Address Coverage for details.

Request costs vary by location type and requested fields. Visit the pricing page for billing details.

New to the API? Start with the Quickstart Tutorial 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.

Shell
        # Client-side
?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&key=YOUR_PUBLIC_KEY

# Server-side
?public_id=MVZWBfGZQnAQn9JtE9CJZjgeB4Q=&private_key=YOUR_PRIVATE_KEY

For complete authentication details and security best practices, see API Keys Documentation.

Request Parameters

Required Parameters

public_id - The unique identifier from an Autocomplete suggestion response.

key or private_key - Your API authentication key. See 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.

Implementation Options

Choose the best integration approach for your project. See the Integration Path Guide for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options.

API 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

Localities Details call
        https://api.woosmap.com/localities/details
  ?public_id=TVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPV9fTVZaV0JmR1pRbkFRbjlKdEU5Q0paamdlQjRRPQ%3D%3D
  &key=YOUR_PUBLIC_API_KEY
    
        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));

    
        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);
});


    
        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)


    
        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();

    
        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

The API returns complete information about the selected location. For complete response schema, see the OpenAPI Specification.

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 for the complete list.

Special Response Features

UK Postal Codes with Addresses - Some UK 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.

Response Examples

Localities Details Address Response
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

Working Code Examples

Example 1: Address and Locality Details

See the complete Localities API Details JS Sample for implementation details.

Example 2: UK Postal Codes with Addresses

See the complete Localities API Details (Postal Codes) JS Sample for implementation details.

Example 3: Geographic Shapes with fields=shape

See the complete Localities API Shape JS Sample for implementation details.

Required Integration:

Alternative Solutions:

‹ Autocomplete Geocoding ›
Was this article helpful?
Have more questions? Submit a request