Setting up a search client

Create an Algolia client and connect to the Onderwijsloket instance.

Algolia provides fast, relevant search across our content collections. Most content collections are indexed to ensure full search coverage.

While Directus includes basic search functionality, Algolia offers significantly better performance and relevance. We therefor recommend to use the Algolia search engine over 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).

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

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(), //
        ],
    })
})

Notice we are importing the Lite Client. The Lite Client includes only basic search and recommendation methods, which is sufficient for interaction with the Onderwijsloket instance.

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

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

/**
 * Note: if we would have imported the full Algolia client,
 * we could have used the following code to search a single index.
 * 
 * The searchSingleIndex method is not available in the lite client.
 */
const response = await client.searchSingleIndex({ indexName: 'faqs', searchParams: { query } });

Calling 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

Minimizing the number of calls

Because Algolia responds instantly, it may be tempting to trigger a request for every keystroke. We recommend implementing a debounce to reduce unnecessary calls. Our own platform uses a 200–300 ms debounce, maintaining a responsive search experience 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.