Search

The Search endpoint enables full-text search and filtering of POIs within your indoor venue. Query POIs by name, category, building, level, or custom attributes to build powerful search experiences.

Most integrations should use a client library. The Map JS API and mobile SDKs 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 instead.

API Endpoint

        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.

        # Client-side
?q=bakery&key=YOUR_PUBLIC_KEY

# Server-side
?q=bakery&private_key=YOUR_PRIVATE_KEY

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

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:

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

Filter by level:

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

Filter by category:

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

Combined filters:

        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:

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

JavaScript example:

        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:

        # 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

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

        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

Autocomplete: Real-time search suggestions as users type
Details: Get complete information for a specific POI
Route: Calculate navigation path between POIs

‹ Autocomplete Details ›