Setting up a search client

Retrieve a search token, configure an Algolia client, and send your first search.

Algolia provides fast, relevant search across most Onderwijsloket content collections. Request the Algolia token first; it is separate from Directus access.

Directus includes basic search, but Algolia gives better relevance and performance. Use it for product search experiences rather than Directus search methods.

The Algolia instance is not part of our API and is not proxied. Both frontend and backend applications call Algolia’s endpoints directly, minimizing latency and enabling near-instant response times (10–30 ms).

The code snippets repository contains production-ready examples used throughout this guide.

Create a client

Algolia provides SDKs for all major languages. The example below uses the JavaScript SDK. Refer to the Algolia documentation for examples in other languages.

Install the Algolia client and its fetch requester and cache dependencies:

pnpm add algoliasearch @algolia/requester-fetch @algolia/client-common

npm install algoliasearch @algolia/requester-fetch @algolia/client-common

yarn add algoliasearch @algolia/requester-fetch @algolia/client-common

bun add algoliasearch @algolia/requester-fetch @algolia/client-common

import { liteClient } from "algoliasearch/lite";
import { createFetchRequester } from "@algolia/requester-fetch";
import {
  createNullCache,
  createBrowserLocalStorageCache,
  createMemoryCache,
  createFallbackableCache
} from "@algolia/client-common";

const ALGOLIA_APP_ID = "WSV9PQ4NXW";
const ALGOLIA_TOKEN = "your_algolia_token_here";

function getUserToken(): string {
  // Implement your logic to retrieve the user token, e.g., from cookies or local storage
  return "anonymous";
}

/**
 * Initialize the Algolia Lite client.
 *
 * For all customization options, see:
 * @see https://www.algolia.com/doc/libraries/sdk/customize
 */
const client = liteClient(ALGOLIA_APP_ID, ALGOLIA_TOKEN, {
  baseHeaders: {
    /**
     * OPTIONAL
     * Set an anonymous user token for tracking purposes.
     * @see https://www.algolia.com/doc/guides/sending-events/concepts/usertoken
     */
    "X-Algolia-UserToken": getUserToken()
  },
  /**
   * OPTIONAL
   * Change the default request implementation.
   * This might be usefull in scenarios where the Algolia client is not
   * detecting the environment (node/browser) correctly.
   *
   * @see https://www.algolia.com/doc/libraries/sdk/v1/customize#change-http-request-methods
   */
  requester: createFetchRequester(),

  /**
   * OPTIONAL
   * Configure caching strategies for requests and responses.
   * @see https://www.algolia.com/doc/libraries/sdk/caching
   */
  requestsCache: createFallbackableCache({
    caches: [
      createBrowserLocalStorageCache({ key: "algolia-requests-cache" }),
      createMemoryCache(),
      createNullCache() // null cache is a no-op
    ]
  }),
  responsesCache: createFallbackableCache({
    caches: [
      createBrowserLocalStorageCache({ key: "algolia-responses-cache" }),
      createMemoryCache(),
      createNullCache() //
    ]
  })
});

The Lite client includes the search and recommendation methods needed for the Onderwijsloket instance, without the larger full-client bundle.

Setting	Value
Application ID	WSV9PQ4NXW
Search Api Key	Personal (see Authentication)
Region	EU

Send your first request

Now that you have the client set up, you can send your first request. The example below searches the faqs index for items related to “salaris”.

// Search the `faqs` index for the query 'salaris'
const query = "salaris";

/**
 * Perform a search request
 *
 * searchForHits is an alias for the search method,
 * with stricter type castings.
 */
const result = await client.searchForHits({
  requests: [
    {
      indexName: "faqs",
      query
    }
  ]
});

const hits = result.results[0]?.hits;

/**
 * The full Algolia client also exposes searchSingleIndex. The Lite client
 * deliberately uses searchForHits for this request.
 */

Call the API directly

If you prefer not to use a client library, you can call Algolia’s REST API endpoints directly. Be aware that retry strategies and caching are not included, and must be implemented manually.

Algolia API Reference

Debounce user input

Algolia is fast enough to invite a request per keystroke. Use a 200–300 ms debounce to keep the interface responsive while reducing request volume by 70–90%.

This is primarily a cost consideration. Algolia uses per-request pricing and, while powerful and easy to use, can be expensive compared to alternatives.

Error handling

Interpret Directus error responses and debug failed API requests.

Authentication

Retrieve your Algolia token from Directus and choose a safe refresh strategy.

Setting up a search client

Create a client

Send your first request

Call the API directly

Debounce user input

Keep in touch with the latest