Source: https://developers.woosmap.com/products/localities/features/autocomplete/

> 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 Autocomplete



**Complete API Specification** : [Autocomplete Endpoint Reference](/api-reference/localities-api/get-localities-autocomplete/)

## What is the Autocomplete Endpoint?

The Localities Autocomplete Endpoint 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

Autocomplete 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 Endpoint](/products/localities/features/details/).

### 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 endpoint 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 Endpoint

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](/products/localities/features/geocoding/) is for. If you need to convert complete addresses to coordinates or find nearby points of interest, use [Geocoding](/products/localities/features/geocoding/) or [Nearby](/products/localities/features/nearby/) respectively. And never store or display addresses using only Autocomplete responses without calling Details first—that is against the [Woosmap Terms of Service](https://www.woosmap.com/policies/terms/).

## Usage Rule

**Autocomplete responses are for display purposes only.** You **must** call the [Details Endpoint](/products/localities/features/details/) 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](/products/localities/concepts/address-coverage/) for details.

New to the API? Start with the [Quickstart Tutorial](/products/localities/tutorials/making-first-request/) for a step-by-step introduction. For parameter optimization and configuration patterns, see [Tuning Localities Results](/products/localities/guides/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. You can also use the `X-Api-Key` header for server-side or mobile authentication.

```shell
# Client-side (query parameter)
?input=paris&key=YOUR_PUBLIC_KEY

# Server-side (query parameter)
?input=paris&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 Overview

### Required Parameters

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

**`key`** or **`private_key`** - Your API authentication key. See [Authentication](#authentication) above.

To autocomplete addresses, set the types parameter to address — addresses aren’t included in the default results.

### Key Optional Parameters

The most commonly used parameters to control search behavior:

**`types`** - Filter by location type (default: `locality|postal_code`). See [Locality Types](/products/localities/concepts/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](/products/localities/concepts/language-support/) for supported languages and regional availability.

**`custom_description`** - Customize the format of suggestion descriptions. See the [Tuning Localities Results](/products/localities/guides/tuning-localities-results/) guide for formatting details.

### Complete Parameter Reference

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

- [OpenAPI Specification](/api-reference/localities-api/get-localities-autocomplete/) - Complete technical reference

- [Tuning Localities Results](/products/localities/guides/tuning-localities-results/) - Configuration guide with examples

## Implementation Options

Choose the best integration approach for your project. See the [Integration Path Guide](/products/localities/guides/integration-path/) for detailed comparison of REST API, Widget, JS SDK, Map JS API, and Store Locator options.

## 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

```javascript
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));
```

```shell
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'
```

```python
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)
```

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

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

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

```ruby
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

Autocomplete returns up to 5 suggestions sorted by relevance. For complete response schema, see the [OpenAPI Specification](/api-reference/localities-api/get-localities-autocomplete/).

### Key Response Fields

**`public_id`** - Unique identifier required for [Details](/products/localities/features/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 & Republic of Ireland: 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](/products/localities/features/details/) with the postal code’s `public_id` to get a list of addresses, then fetch details for a specific address.

## Response Examples

```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": "52MnrbHVWH21CLWH8VY/YWKhqeM=",
        "type": "locality",
        "types": ["locality", "village"],
        "description": "London Apprentice, Cornwall, United Kingdom",
        "matched_substrings": { "description": [{ "offset": 0, "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](/js-samples/localities-api-autocomplete/) for implementation details.

https://demo.woosmap.com/js-samples/samples/localities-api-autocomplete/app/dist/
[](https://demo.woosmap.com/js-samples/samples/localities-api-autocomplete/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-autocomplete/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-api-autocomplete/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-api-autocomplete)

### Example 2: Advanced Multi-Type Address Search

See the complete [Localities API Autocomplete Advanced JS Sample](/js-samples/localities-api-autocomplete-advanced/) for implementation details.

https://demo.woosmap.com/js-samples/samples/localities-api-autocomplete-advanced/app/dist/
[](https://demo.woosmap.com/js-samples/samples/localities-api-autocomplete-advanced/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-autocomplete-advanced/app?file=index.ts)
- [JsFiddle](https://jsfiddle.net/gh/get/library/pure/woosmap/js-samples/tree/master/dist/samples/localities-api-autocomplete-advanced/jsfiddle)
- [Clone on Github](https://github.com/Woosmap/js-samples/tree/sample/localities-api-autocomplete-advanced)

## Related Features

**Essential Integration:**

- [Localities Details](/products/localities/features/details/) - **Required** to get complete place information after selection

**Alternative Solutions:**

- [Localities Geocoding](/products/localities/features/geocoding/) - Convert full addresses to coordinates (batch processing)
- [Localities Nearby](/products/localities/features/nearby/) - Find points of interest near a location

**Implementation Guides:**

- [Widget Guide](/products/localities/guides/widget-guide/) - Pre-built UI component
- [JS API Guide](/products/localities/guides/js-guide/) - Custom integration
- [Tuning Results](/products/localities/guides/tuning-localities-results/) - Parameter optimization guide