Source: https://developers.woosmap.com/products/stores-api/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

# Autocomplete Search



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

## What is the Autocomplete Endpoint?

The Autocomplete Endpoint provides partial-text matching on your asset names. The [Search endpoint](/products/stores-api/features/search/) only supports exact-match filters on fields like `name`, `type`, or `city`. Autocomplete is the way to let users find stores by typing part of a name.

### What It Does

Autocomplete matches user input against the [localizedNames](/api-reference/data-api/post-stores/) you have defined for your assets and returns a list of predictions. Each prediction includes a `store_id` that you use to fetch the complete store record via the [Search endpoint](/products/stores-api/features/search/) or a `GET /stores/{storeId}` call to the [Data Management endpoint](/products/stores-api/features/data-management/#get-assets).

### Response Structure

Each prediction contains a `store_id` (the identifier to retrieve full store details), a `name` (the localized name in the requested language, or the default name if that language is unavailable), `types` (the asset’s type classifications), a `highlighted` field (an HTML string with matched substrings in bold), and a `matched_substrings` list (with `offset` and `length` for each match, useful for custom highlighting in your UI).

### Key Characteristics

Autocomplete returns lightweight responses for displaying suggestions in a search-as-you-type interface. To get complete store information (location, address, opening hours), retrieve the asset by its `storeId`:

```shell
curl "https://api.woosmap.com/stores/YOUR_STORE_ID?key=YOUR_KEY"
```

## When to Use This Endpoint

Use Autocomplete when building search-as-you-type interfaces where users need to find stores by name, such as store locators, delivery point selectors, or any UI where users search for a specific asset by its localized name.

Don’t use Autocomplete for geographic or attribute-based store searches, that’s what [Search](/products/stores-api/features/search/) is for. If you need to find stores near a location or filter by type, tag, or custom properties, use that endpoint instead.

New to the API? Start with the [Making Your First Request](/products/stores-api/tutorials/making-first-request/) tutorial for a step-by-step introduction. For parameter optimization, see [Tuning Search Results](/products/stores-api/guides/tuning-search-results/).

## API Endpoint

```http
GET https://api.woosmap.com/stores/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 restrictions and a valid `Referer` header. 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 (Referer header is sent automatically by browsers)
?query=localized:"street"&key=YOUR_PUBLIC_KEY

# Server-side (query parameter)
?query=localized:"street"&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

**`query`** - The search query string. Use the `localized` field for full-text autocomplete search (e.g., `localized:"street"`). You can also combine it with other [Query Syntax](/products/stores-api/concepts/query-syntax/) fields.

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

### Key Optional Parameters

**`language`** - Return the localized name in a specific language where available (e.g., `en`, `fr`, `de`). If the requested language is not available for an asset, the default `name` property is returned instead.

**`limit`** - Maximum number of predictions to return. Default is `5`, maximum is `50`.

**Other query fields** - The `query` parameter supports all fields from the [Query Syntax](/products/stores-api/concepts/query-syntax/) reference, such as `type`, `tag`, `city`, `country`, and `user.*` properties. You can combine `localized` with these fields to narrow results (e.g., `localized:"street" AND type:"restaurant"`).

The `localized` field is **only** available on the Autocomplete endpoint, not on the Search endpoint. All other query fields work on both endpoints.

## Implementation Options

Choose the best integration approach for your project. See the [Integration Path Guide](/products/stores-api/guides/integration-path/) for a detailed comparison of available options.

## Request Examples

### Basic Autocomplete Search

```shell
curl "https://api.woosmap.com/stores/autocomplete/?query=localized:\"street\"&language=en&key=YOUR_KEY"
```

### Autocomplete with Type Filter

```shell
curl "https://api.woosmap.com/stores/autocomplete/?query=localized:\"street\"+AND+type:\"restaurant\"&language=en&key=YOUR_KEY"
```

### Multi-Language Examples

Here we assume that the user typed `street` and we send their request with the parameter `language` set to `en`.

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

fetch("https://api.woosmap.com/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&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/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'
```

```python
import requests

url = "https://api.woosmap.com/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&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/stores/autocomplete/
  ?language=en
  &limit=3
  &query=localized%3Astreet
  &key=YOUR_PUBLIC_API_KEY
```

```javascript
const axios = require('axios');

let config = {
  method: 'get',
  maxBodyLength: Infinity,
  url: 'https://api.woosmap.com/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&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/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&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/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&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 a list of predictions sorted by relevance to the user’s input.

### Key Response Fields

**`store_id`** - Unique identifier for the asset. Use this to retrieve full store details via the [Search endpoint](/products/stores-api/features/search/) (e.g., `query=idstore:="YOUR_STORE_ID"`) or `GET /stores/{storeId}` on the [Data Management endpoint](/products/stores-api/features/data-management/#get-assets).

**`name`** - The localized name of the asset in the requested `language`, or the default name if that language is unavailable

```json
"name": "My Store on Main Street"
```

**`types`** - Array of type classifications for the asset

```json
"types": ["Coffee shop"]
```

**`highlighted`** - An HTML-formatted string with matched substrings wrapped in bold tags, ready for display in your UI

```json
"highlighted": "My Store on Main <b>Street</b>"
```

**`matched_substrings`** - Character positions of matched text (for custom highlighting)

```json
"matched_substrings": [
  {"offset": 22, "length": 6}
]
```

## Response Examples

```json
{
  "predictions":
    [
      {
        "store_id": "2670",
        "name": "Sun Street",
        "types": ["Coffee shop"],
        "matched_substrings": [{ "offset": 4, "length": 6 }],
        "highlighted": "Sun <b>Street</b>",
      },
      {
        "store_id": "16069",
        "name": "7th Street",
        "types": ["Coffee shop"],
        "matched_substrings": [{ "offset": 4, "length": 6 }],
        "highlighted": "7th <b>Street</b>",
      },
      {
        "store_id": "1013873",
        "name": "The Street",
        "types": ["Coffee shop"],
        "matched_substrings": [{ "offset": 4, "length": 6 }],
        "highlighted": "The <b>Street</b>",
      },
    ],
}
```

## Troubleshooting

| Issue | Common Cause | Solution |
| --- | --- | --- |
| No results returned | Missing or incorrect `localized` field | Ensure you use `query=localized:"your text"` for full-text search |
| Wrong language in results | Language not set or unavailable | Set `language` parameter; verify that `localizedNames` include that language |
| Only exact matches returned | Using `name` or `city` instead of `localized` | Switch to the `localized` field for fuzzy/partial matching |
| Suggestions too slow | No debouncing | Implement 300-500ms debounce on user input |
| Missing store details | Using autocomplete response only | Retrieve full details via `GET /stores/{storeId}` on [Data Management](/products/stores-api/features/data-management/#get-assets) |
| API key error | Wrong key type or restrictions | Check key type (public vs private) and referer settings |

## Usage Limits & Quotas

- **Rate Limit** : 25 queries per second (QPS) per project
- Exceeding limits returns `429 Too Many Requests`
- Contact support for higher quotas

## Working Code Examples

### Example: Autocomplete Search on Localized Names

See the complete [Stores Autocomplete API JS Sample](/js-samples/stores-search-autocomplete-api/) for implementation details.

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

For multi-language code examples (cURL, JavaScript, Node.js, Python, Java, Ruby), see the [API Reference](/api-reference/search-api/get-stores-autocomplete/).

## Related Features

- [Data Management](/products/stores-api/features/data-management/) - Retrieve full store details and manage your store data
- [Search](/products/stores-api/features/search/) - Query stores by attributes and geographic proximity
- [Tuning Search Results](/products/stores-api/guides/tuning-search-results/) - Parameter optimization guide
- [Integration Path](/products/stores-api/guides/integration-path/) - Choose the right integration approach
- [Stores API Overview](/products/stores-api/overview/) - Product overview