May 24, 2022

Localities Autocomplete API

Build predictive address search with real-time location suggestions. Learn implementation patterns, best practices, and how to chain Autocomplete with Details for complete address data.

1. What is the Autocomplete API?
2. When to Use This API
3. Usage Rule
4. API Endpoint
5. Request Parameters Overview
6. Implementation Options
7. API Request Examples
8. Understanding the Response
9. Response Examples
10. Troubleshooting
11. Usage Limits & Quotas
12. Working Code Examples
13. Related Features

Complete API Specification: Autocomplete API Reference

What is the Autocomplete API?

The Localities Autocomplete API is a text-based search service that returns location suggestions as users type. It’s designed for building predictive search interfaces where you need to help users find and select geographic locations quickly and accurately, including cities, postal codes, addresses, airports, and administrative areas.

What It Does

The API returns up to 5 suggestions for any text input, sorted by relevance. It matches on full words and substrings, so it works even with partial input. You get worldwide coverage for addresses, cities, postal codes, airports, and more. Each suggestion includes a public_id that you use to fetch complete details via the Details API.

Response Structure

Each suggestion contains a public_id (required identifier to get full details), a description (human-readable text to display), a list of types (categories like locality, address, or postal_code), and matched_substrings (character positions for highlighting matched text in your UI).

Key Characteristics

Autocomplete returns lightweight responses optimized for displaying suggestions, not for final use. You must chain it with the Details API to get complete address information. It’s designed for low-latency responses as users type, returning results that match even partial words. You can control what types of locations appear, restrict to specific countries, bias toward a geographic area, and customize how suggestions are displayed.

When to Use This API

Use Autocomplete when building search-as-you-type interfaces for location input, such as e-commerce checkout forms, delivery address capture, store locators, or travel booking interfaces. It’s perfect for any UI where users need to quickly find and select a location from suggestions.

Don’t use Autocomplete for batch processing—that’s what Geocoding is for. If you need to convert complete addresses to coordinates or find nearby points of interest, use Geocoding or Nearby respectively. And never store or display addresses using only Autocomplete responses without calling Details first—that is against the Woosmap Terms of Service.

Usage Rule

Autocomplete responses are for display purposes only. You must call the Details API to get complete address data before storing, processing, or displaying locations as final results. Using Autocomplete responses directly violates terms of service and will result in Details-level billing for all Autocomplete calls.

Autocomplete and Details on address and postal_code may require specific product activation. See Address Coverage for details.

New to the API? Start with the Quickstart Tutorial for a step-by-step introduction. For parameter optimization and configuration patterns, see Tuning Localities Results.

API Endpoint

http

        GET https://api.woosmap.com/localities/autocomplete/

    

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
?input=paris&key=YOUR_PUBLIC_KEY

# Server-side
?input=paris&private_key=YOUR_PRIVATE_KEY

    

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

Request Parameters Overview

Required Parameters

input - The search text string (truncated after 150 characters).

key or private_key - Your API authentication key. See Authentication above.

Key Optional Parameters

The most commonly used parameters to control search behavior:

types - Filter by location type (default: locality|postal_code). See Locality Types for all available types and their descriptions. Common values: address, locality, postal_code, point_of_interest, admin_level.

components - Restrict to specific countries using ISO 3166-1 codes (e.g., country:fr|country:gb). There is no limit on the number of countries you can specify. Highly recommended for better accuracy.

location - Bias results toward a geographic point without excluding distant matches. Used with radius parameter. Radius in meters (default: 100,000).

language - Return results in a specific language where available (e.g., fr, de, en). See Language Support for supported languages and regional availability.

custom_description - Customize the format of suggestion descriptions. See the Tuning Localities Results guide for formatting details.

Complete Parameter Reference

For all available parameters, data types, constraints, and advanced options, see:

• OpenAPI Specification - Complete technical reference

• Tuning Localities Results - Configuration guide with examples

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 Worldwide Search

Shell

        curl "https://api.woosmap.com/localities/autocomplete/?input=london&key=YOUR_KEY"

    

Country-Specific Search

Shell

        # Search only in Great Britain
curl "https://api.woosmap.com/localities/autocomplete/?input=lond&components=country:gb&key=YOUR_KEY"

    

Address Search with Multiple Countries

Shell

        # Search Addresses in United States and Canada
curl "https://api.woosmap.com/localities/autocomplete/?input=main+street&types=address&components=country:us|country:ca&key=YOUR_KEY"

    

Location-Biased Search

Shell

        # Prioritize results near London, UK
curl "https://api.woosmap.com/localities/autocomplete/?input=westminster&location=51.5074,-0.1278&radius=50000&key=YOUR_KEY"

    

Multi-Language Examples

Localities Autocomplete call

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/localities/autocomplete/
  ?components=country%3Agb
  &input=Lond
  &no_deprecated_fields=true
  &key=YOUR_PUBLIC_API_KEY
    

        curl -L 'https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    

        const requestOptions = {
  method: "GET",
  redirect: "follow"
};

fetch("https://api.woosmap.com/localities/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&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/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&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/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&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/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&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/autocomplete/?input=Lond&components=country%3Agb&no_deprecated_fields=true&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 up to 5 suggestions sorted by relevance. For complete response schema, see the OpenAPI Specification.

Key Response Fields

public_id - Unique identifier required for Details requests

JSON

        "public_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ="

    

description - Human-readable suggestion text (customizable via custom_description)

JSON

        "description": "Paris, Île-de-France, France"

    

type

The category of the result (e.g., locality, postal_code, address)

JSON

        "type": "locality"

    

matched_substrings - Text positions matching user input (for highlighting)

JSON

        "matched_substrings": [
{"offset": 0, "length": 5}
]

    

Special Features by Territory

France & Italy: Related Postal Codes

Locality suggestions include a related field with associated postal codes:

JSON

        {
  "description": "Strasbourg, Bas-Rhin, France",
  "type": "locality",
  "related": {
    "postal_codes": [
      {
        "public_id": "8yWv6KjsafWjcMSm64/6MI9h8vo=",
        "description": "67000, Strasbourg, France"
      },
      {
        "public_id": "YByyB1s6RmrbbLZmeOhQ27Y3DjQ=",
        "description": "67100, Strasbourg, France"
      }
    ]
  }
}

    

You can fetch details for each postal code using its public_id.

Related postal code descriptions can also be customized with the custom_description parameter.

United Kingdom: Address Availability

Postal codes include has_addresses to indicate if street-level addresses are available:

JSON

        {
  "description": "SW1A 1AA, London, United Kingdom",
  "type": "postal_code",
  "has_addresses": true
}

    

When true, call Details with the postal code’s public_id to get a list of addresses, then fetch details for a specific address.

Response Examples

Localities Autocomplete Collection Response

JSON

        {
  "localities":
    [
      {
        "public_id": "Ch6qA8cLmvyvEEoFy6nYeFcEdNU=",
        "type": "locality",
        "types": ["locality", "city"],
        "description": "London, City of London, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 0, "length": 4 }] },
      },
      {
        "public_id": "m/T2C4YI2LgszkKXrELBC+9dfC8=",
        "type": "locality",
        "types": ["locality", "city"],
        "description": "Derry/Londonderry, Derry City and Strabane, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 6, "length": 4 }] },
      },
      {
        "public_id": "J6eISGMjjvQwPkao8rsByB3aVwM=",
        "type": "locality",
        "types": ["locality", "village"],
        "description": "London Colney, Hertfordshire, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 0, "length": 4 }] },
      },
      {
        "public_id": "4Ew1mvbob3vobGMQ44AdRNY/5xE=",
        "type": "locality",
        "types": ["locality", "village"],
        "description": "Little London, Hampshire, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 7, "length": 4 }] },
      },
      {
        "public_id": "S/5AkUmMBhX35qVI2jR38+dALwk=",
        "type": "locality",
        "types": ["locality", "city"],
        "description": "City of London, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 8, "length": 4 }] },
      },
    ],
}

    

Troubleshooting

Issue	Common Cause	Solution
Too many irrelevant suggestions	No country restriction	Add components: { country: [...] }
No results returned	Over-filtering	Remove or relax excluded_types, increase radius
Wrong language in results	Language not set	Explicitly set language parameter
Suggestions too slow	No debouncing	Implement 300-500ms debounce on input
Missing addresses	Wrong type selected	Use types: "address"
API key error	Wrong key type or restrictions	Check key type (public vs private) and referer settings

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: Basic Locality and Postal Code Search

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

• CodeSandbox
• JsFiddle
• Clone on Github

Example 2: Advanced Multi-Type Address Search

See the complete Localities API Autocomplete Advanced JS Sample for implementation details.

• CodeSandbox
• JsFiddle
• Clone on Github

Related Features

Essential Integration:

• Details API - Required to get complete place information after selection

Alternative Solutions:

• Geocoding API - Convert full addresses to coordinates (batch processing)
• Nearby API - Find points of interest near a location

Implementation Guides:

• Widget Guide - Pre-built UI component
• JS API Guide - Custom integration
• Tuning Results - Parameter optimization guide

‹ Get Started Details ›

Was this article helpful?

Have more questions? Submit a request