Autocomplete Search

Text-based store search that returns suggestions based on localised asset names.

Complete API Specification: Autocomplete Endpoint Reference

What is the Autocomplete Endpoint?

The Autocomplete Endpoint provides partial-text matching on your asset names. The Search endpoint 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 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 or a GET /stores/{storeId} call to the Data Management endpoint.

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 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 tutorial for a step-by-step introduction. For parameter optimization, see 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.

Shell

        # Client-side (Referer header is sent automatically by browsers)
?query=localized:"street"&key=YOUR_PUBLIC_KEY

# Server-side
?query=localized:"street"&private_key=YOUR_PRIVATE_KEY

    

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

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 fields.

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

Search only among stores of type restaurant

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.

Sample Autocomplete call

URL

cURL

JavaScript

NodeJS

Python

Java

Ruby

        https://api.woosmap.com/stores/autocomplete/
  ?language=en
  &limit=3
  &query=localized%3Astreet
  &key=YOUR_PUBLIC_API_KEY
    

        curl -L 'https://api.woosmap.com/stores/autocomplete/?language=en&query=localized%3Astreet&limit=3&key=YOUR_PUBLIC_API_KEY' \
-H 'Referer: http://localhost'

    

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

    

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


    

        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)


    

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

    

        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 (e.g., query=idstore:="YOUR_STORE_ID") or GET /stores/{storeId} on the Data Management endpoint.

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

Sample Autocomplete response

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
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 for implementation details.

• CodeSandbox
• JsFiddle
• Clone on Github

For multi-language code examples (cURL, JavaScript, Node.js, Python, Java, Ruby), see the API Reference.

Related Features

• Data Management - Retrieve full store details and manage your store data
• Search - Query stores by attributes and geographic proximity
• Tuning Search Results - Parameter optimization guide
• Integration Path - Choose the right integration approach
• Stores API Overview - Product overview

‹ Search Data Management ›

Was this helpful?

Failed to send feedback. Please try again.

Thanks for your feedback!