Source: https://developers.woosmap.com/products/indoor-api/features/search/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Search



**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 Search Endpoint?

Performs full-text searches across POIs, returning complete GeoJSON data including geometry, enabling filtered listings and map-based search results.

## When to Use This Endpoint

Search is the right choice when you need complete POI data — coordinates, category, custom attributes — rather than just names for a type-ahead input. It suits search results pages, category browsers ("all restaurants on Level 2"), map-based listings where you'll render markers from the GeoJSON geometry, and server-side batch queries. If you only need quick name suggestions as the user types, use [Autocomplete](/products/indoor-api/features/autocomplete/) instead.

## API Endpoint

```http
GET https://api.woosmap.com/indoor/venues/{venueId}/pois/search
```

### 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)
?q=bakery&key=YOUR_PUBLIC_KEY

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

### Search Parameters

| Parameter | Type   | Description                                             |
| --------- | ------ | ------------------------------------------------------- |
| `q`       | string | Search query text (e.g., "coffee shop", "meeting room") |
| `ref`     | string | Search by POI reference ID                              |
| `id`      | string | Search by POI internal ID                               |

### Filter 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 (uses `woosmap:category` property) |
| `advancedFilter` | string  | Advanced filter expression for complex queries            |

### Pagination Parameters

| Parameter        | Type    | Description                               |
| ---------------- | ------- | ----------------------------------------- |
| `page`           | integer | Page number (default: 1)                  |
| `stores_by_page` | integer | Number of results per page (default: 100) |

### Request Examples

**Basic text search:**

```bash
curl "https://api.woosmap.com/indoor/venues/gdn_doc/pois/search?q=bakery&key=YOUR_API_KEY"
```

**Filter by level:**

```bash
curl "https://api.woosmap.com/indoor/venues/gdn_doc/pois/search?level=1&key=YOUR_API_KEY"
```

**Filter by category:**

```bash
curl "https://api.woosmap.com/indoor/venues/gdn_doc/pois/search?category=food_and_drinks&key=YOUR_API_KEY"
```

**Combined filters:**

```bash
curl "https://api.woosmap.com/indoor/venues/gdn_doc/pois/search?q=coffee&level=0&building=terminal_a&key=YOUR_API_KEY"
```

**Search by reference:**

```bash
curl "https://api.woosmap.com/indoor/venues/gdn_doc/pois/search?ref=bakery001&key=YOUR_API_KEY"
```

**JavaScript example:**

```javascript
const searchPOIs = async (venueId, query, filters = {}) => {
  const params = new URLSearchParams({
    q: query,
    key: "YOUR_API_KEY",
    ...filters,
  });

  const response = await fetch(`https://api.woosmap.com/indoor/venues/${venueId}/pois/search?${params}`);
  return response.json();
};

// Usage
const results = await searchPOIs("gdn_doc", "restaurant", { level: 1 });
```

## Response Format

The API returns a GeoJSON FeatureCollection with an array of features (POIs) and pagination metadata. Each feature includes complete geometry (coordinates), properties (name, level, building, category, custom attributes), and optional distance/duration fields.

### Response Fields

| Field                                    | Type    | Description                       |
| ---------------------------------------- | ------- | --------------------------------- |
| `type`                                   | string  | Always "FeatureCollection"        |
| `features`                               | array   | Array of GeoJSON Feature objects  |
| `features[].id`                          | integer | Internal POI identifier           |
| `features[].geometry`                    | object  | GeoJSON geometry with coordinates |
| `features[].properties.name`             | string  | POI display name                  |
| `features[].properties.ref`              | string  | Custom reference ID (if set)      |
| `features[].properties.level`            | integer | Floor level number                |
| `features[].properties.building`         | string  | Building identifier               |
| `features[].properties.woosmap:category` | string  | POI category                      |
| `pagination`                             | object  | Pagination information            |
| `pagination.page`                        | integer | Current page number               |
| `pagination.page_count`                  | integer | Total number of pages             |
| `pagination.per_page`                    | integer | Results per page                  |
| `pagination.total`                       | integer | Total results found               |

### Status Codes

| Code  | Description                |
| ----- | -------------------------- |
| `200` | Request successful         |
| `400` | Invalid request parameters |
| `401` | Invalid or missing API key |
| `404` | Venue not found            |
| `429` | Rate limit exceeded        |

## Advanced Filtering

Use the `advancedFilter` parameter for complex queries:

```bash
# POIs with specific amenity type
?advancedFilter=amenity:="restaurant"

# POIs on multiple levels
?advancedFilter=level:0 OR level:1

# Combine multiple conditions
?advancedFilter=woosmap:category:="retail" AND level:1
```

### Filter Syntax

| Operator | Description | Example                        |
| -------- | ----------- | ------------------------------ |
| `:=`     | Exact match | `name:="Coffee Shop"`          |
| `:`      | Contains    | `name:"coffee"`                |
| `AND`    | Logical AND | `level:1 AND category:="food"` |
| `OR`     | Logical OR  | `level:0 OR level:1`           |

## Implementation Notes

The default page size is 100 results — always check `pagination.page_count` and page through results if your venue has more POIs than that. Apply `building` and `level` filters whenever the user's context is known; this keeps results relevant and reduces response size. For search interfaces, debounce input by 300–500 ms so requests only fire once the user pauses. Category listings and venue directories change infrequently, so they're good candidates for client-side caching. The response is a standard GeoJSON `FeatureCollection`, which means you can pass features directly to `indoorRenderer.highlightFeature()` or any GeoJSON-aware map layer without transformation.

## Usage with Map JS API

```javascript
// Using Indoor Service for search
const indoorService = new window.woosmap.map.IndoorService();

// Search for POIs
indoorService.search(
  "gdn_doc", // venueId
  "restaurant", // query
  (results) => {
    // results is a GeoJSON FeatureCollection
    console.log("Found POIs:", results.features.length);

    results.features.forEach((feature) => {
      console.log(feature.properties.name, feature.geometry.coordinates);
    });
  },
  null, // ref (optional)
  null, // id (optional)
  "level:1" // advancedFilter (optional)
);
```

### Display Results on Indoor Map

```javascript
const indoorRenderer = new woosmap.map.IndoorRenderer({
  venue: "gdn_doc",
  centerMap: true,
});
indoorRenderer.setMap(map);

// Listen for venue load, then search and display
indoorRenderer.addListener("indoor_venue_loaded", () => {
  const indoorService = new woosmap.map.IndoorService();

  indoorService.search("gdn_doc", "coffee", (results) => {
    results.features.forEach((feature) => {
      // Highlight each matching POI
      indoorRenderer.highlightFeature(feature.id.toString(), true);
    });
  });
});
```

## Comparison: Search vs Autocomplete

| Feature            | Search                    | Autocomplete                  |
| ------------------ | ------------------------- | ----------------------------- |
| Response format    | GeoJSON FeatureCollection | Predictions array             |
| Includes geometry  | ✅ Yes                    | ❌ No                         |
| Pagination         | ✅ Yes                    | ❌ No (limited results)       |
| Advanced filtering | ✅ Full support           | ⚠️ Basic filters              |
| Best for           | Full search, map display  | Quick suggestions, type-ahead |
| Typical use        | Search results page       | Search input field            |

## Related Endpoints

- **[Autocomplete](/products/indoor-api/features/autocomplete/)**: Real-time search suggestions as users type
- **[Details](/products/indoor-api/features/feature-details/)**: Get complete information for a specific POI
- **[Route](/products/indoor-api/features/route/)**: Calculate navigation path between POIs