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



**Most integrations should use a client library.** The [Map JS API](/products/indoor-api/indoor-js-api/reference/) and [mobile SDKs](/products/mobile/get-started/) handle authentication, map binding, and error handling automatically. Call the REST API directly only when building a backend service or a platform where the JS library is unavailable.

## What is the Autocomplete Endpoint?

Returns real-time search suggestions for POIs as users type, enabling fast location discovery within indoor venues.

## When to Use This Endpoint

Autocomplete is suited to interactive search inputs — search bars, wayfinding kiosks, and voice interfaces — where users need instant suggestions from partial queries like "coffee" or "exit." It works across POI names and attributes, can be filtered by building, floor, or category, and supports multiple languages.

For scenarios where you need complete GeoJSON geometry or paginated results, use the [Search endpoint](/products/indoor-api/features/search/) instead.

## API Endpoint

```http
GET https://api.woosmap.com/indoor/venues/{venueId}/pois/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.

```bash
# Client-side (query parameter)
?query=bakery&key=YOUR_PUBLIC_KEY

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

| Parameter              | Type   | Description                               |
| ---------------------- | ------ | ----------------------------------------- |
| `key` or `private_key` | string | Your Woosmap API key                      |
| `query`                | string | User's search input (e.g., "coffee shop") |

### Key Optional Parameters

| Parameter  | Type    | Description                                            |
| ---------- | ------- | ------------------------------------------------------ |
| `building` | string  | Filter results to specific building                    |
| `level`    | integer | Filter results to specific floor level                 |
| `category` | string  | Filter by POI category                                 |
| `language` | string  | Language code for localized results (e.g., "en", "fr") |
| `limit`    | integer | Maximum number of results (default: 5)                 |

### Request Example

```bash
GET https://api.woosmap.com/indoor/venues/gdn_doc/pois/autocomplete?query=bakery&key=YOUR_API_KEY
```

```javascript
const response = await fetch(
  `https://api.woosmap.com/indoor/venues/${venueId}/pois/autocomplete?` + `query=bakery&key=YOUR_API_KEY`
);
const suggestions = await response.json();
```

## Response Format

The API returns a predictions array with POI suggestions, along with pagination information. Each prediction includes the POI's identifier, name, building, level, and optional distance/duration if a location was provided.

### Response Fields

| Field                    | Type    | Description                                               |
| ------------------------ | ------- | --------------------------------------------------------- |
| `predictions`            | array   | Array of POI suggestions                                  |
| `predictions[].id`       | string  | Unique identifier for the POI (use with Details endpoint) |
| `predictions[].name`     | string  | Display name of the POI                                   |
| `predictions[].building` | string  | Building identifier                                       |
| `predictions[].level`    | integer | Floor level number                                        |
| `predictions[].category` | array   | POI category classification                               |
| `predictions[].distance` | number  | Distance in meters from location (if provided)            |
| `predictions[].duration` | number  | Duration in seconds from location (if provided)           |
| `pagination`             | object  | Pagination metadata (page, total, per_page)               |

### Status Codes

- `OK`: Request successful
- `ZERO_RESULTS`: No matching POIs found
- `INVALID_REQUEST`: Missing or invalid parameters
- `REQUEST_DENIED`: Invalid API key or unauthorized access
- `OVER_QUERY_LIMIT`: Rate limit exceeded

## Implementation Notes

Debounce requests by 300–500 ms so the API is only called once the user has paused typing, and only trigger from 2–3 characters to avoid low-value results. Apply `building` and `level` filters whenever the user's current context is known — this keeps suggestions relevant and reduces noise in large venues. When building on top of the Map JS API, pass results directly to `indoorRenderer.highlightFeature()` to avoid a redundant Details call.

## Usage with Map JS API

```javascript
const indoorService = new window.woosmap.map.IndoorService();

indoorService.autocomplete(
  "gdn_doc", // venueId
  "bakery", // query
  (predictions) => {
    predictions.predictions.forEach((p) => {
      console.log(p.name, "— level", p.level);
    });
  }
);
```