Alternative implementations

Alternative implementations for Algolia’s Guides.

If you aren’t developing a React or JavaScript app, you can integrate the Algolia Guides into your app with an API client.

Installation

The Algolia Guides API Client package is available on the npm registry.

npm

npm install @algolia/generative-experiences-api-client

Usage

Guide headlines

The getHeadlines method lets you retrieve different guides for your app.

JavaScript

import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

client
  .getHeadlines({
    category: guidesCategory,
  })
  .then((response) => console.log(response));

You can dynamically generate headlines using the getOrGenerateHeadlines method by passing a source parameter. For this method you must use an API key with the search and addObject ACLs.

Only use this method on your backend or if you provide a layer of authentication.

JavaScript

import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  writeAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

client
  .getOrGenerateHeadlines({
    category: guidesCategory,
    source: "generated",
  })
  .then((response) => console.log(response));

Parameters

category · string · required

The category used for retrieving the headlines.

maxHeadlines · number · default: 4

The number of headlines to display (between 1 and 1000).

source · "index" | "generated" | "combined" · default: "index"

The source of the headlines.

tone · "natural" | "friendly" | "professional" · default: "natural"

The tone used by the model.

language_code · "en_US" | "de_DE" | "fr_FR" · default: "en_US"

The language code used for generating headlines.

custom_content · string

The customized instructions that the model should take into account for generating content, for example, to refine the focus of the article, add constraints, or adjust to a target audience.

keywords · string

A list of keywords that the model should highlight in the generated content.

onlyPublished · boolean · default: true

Whether to only return headlines with generated content.

Guide content

The getContent method lets you retrieve the content of a guide.

JavaScript

import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

client
  .getContent({
    objectID: guideID,
  })
  .then((response) => console.log(response));

You can dynamically generate the content of a guide using the getOrGenerateContent method by passing a source parameter. For this method you must use an API key with the search and addObject ACLs.

Only use this method on your backend implementation or if you provide a layer of authentication.

JavaScript

import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  writeAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

client
  .getOrGenerateContent({
    objectID: guideID,
    source: "generated",
  })
  .then((response) => console.log(response));

Parameters

objectID · string · required

The ID of the guide to retrieve.

source · "index" | "generated" | "combined" · default: "index"

The source of the guide content.

type · "shopping_guide" | "category_guide" · default: "shopping_guide"

If source is generated: the type of guide to generate.

tone · "natural" | "friendly" | "professional" · default: "natural"

The tone used by the model.

language_code · "en_US" | "de_DE" | "fr_FR" · default: "en_US"

The language code used for generating headlines.

custom_content · string

The customised instructions that the model should take into account for generating content, for example, to refine the focus of the article, add constraints, or adjust to a target audience.

keywords · string

A list of keywords that the model should highlight in the generated content.

onlyPublished · boolean · default: true

Whether to only return headlines with generated content.

Gather feedback

The vote method lets you gather feedback for the guide’s headlines or content.

This feature uses the Insights API to gather events related to Guides feedback. This requires a a user token.

JavaScript

import { createClient } from "@algolia/generative-experiences-api-client";

const client = createClient({
  appId: "ALGOLIA_APPLICATION_ID",
  indexName: "INDEX_NAME",
  searchOnlyAPIKey: "ALGOLIA_API_KEY",
  region: "us",
});

client.vote({
  objectID: guideID,
  voteType: "upvote",
  voteTarget: "content",
  userToken: userToken,
});

Parameters

objectIDs · string · required

List of object IDs for which to gather feedback.

userToken · string · required

The user token for computing feedback.

voteType · string · required

The feedback type: upvote or downvote.

voteTarget · "content" | "headline" · default: "content"

The feedback target.