Related ContentSpringboard Query API

Table of Contents

Prerequisites
Basic relatedContent request
Advanced search request
Return only specified fields
Analytics data

This endpoint finds and returns documents that are semantically similar. The request requires either:

The document.title with the optional field of document.description, or
The id obtained from the search result of the web page

You cannot use both the document.title and the id in the same request.

Send a POST request to the relatedContent endpoint to create a query and receive a response.

Prerequisites

Before using this endpoint, use the Authentication API with the scope value of connectedsearch.query to generate an access token. The access token is used to authenticate your requests.

You must also supply the APPLICATION_ID value, as the request URL requires it. To obtain the value, click the Integrations icon from the Applications UI sidebar and then click the APIs tab. The value is in the Application ID field.

Basic `relatedContent` request

A basic relatedContent request requires one of the following strings that contain three fields and values.

probe.title, utcOffset, and sessionId
probe.documentId, utcOffset, and sessionId

The request can contain either the probe.title or the probe.documentId. You cannot use both probe.title and probe.documentId in the same request.

Key Description

Key	Description
`probe.title`	The name of the document. Documents that are semantically similar (not case-sensitive) to the existing `document.title` are returned. If `probe.title` matches the `document.title` of a result on the webpage, it is filtered out and not returned in the results. Cannot be submitted in the request if `probe.documentId` is submitted.
`probe.documentId`	The ID of the document. Documents that are semantically similar to the existing `id` are returned. If `probe.documentId` matches the `id` of a result on the webpage, it is not returned in the results. Cannot be submitted in the request if `probe.title` is submmitted.
`utcOffset`	The difference between Coordinated Universal Time (UTC) and your time zone, formatted with six characters as `±00:00`.
`sessionId`	Unique value that identifies the user’s session. Consider passing the session ID value from your user’s browser session as the value of `sessionId`. For more information, see the MDN developer documentation for sessionStorage.

probe.title

The name of the document. Documents that are semantically similar (not case-sensitive) to the existing document.title are returned. If probe.title matches the document.title of a result on the webpage, it is filtered out and not returned in the results. Cannot be submitted in the request if probe.documentId is submitted.

probe.documentId

The ID of the document. Documents that are semantically similar to the existing id are returned. If probe.documentId matches the id of a result on the webpage, it is not returned in the results. Cannot be submitted in the request if probe.title is submmitted.

utcOffset

The difference between Coordinated Universal Time (UTC) and your time zone, formatted with six characters as ±00:00.

sessionId

Unique value that identifies the user’s session. Consider passing the session ID value from your user’s browser session as the value of sessionId. For more information, see the MDN developer documentation for sessionStorage.

Example request using `title`

The following example displays a minimal relatedContent cURL request using title.

Replace APPLICATION_ID with your Application ID. Replace ACCESS_TOKEN with the access token you generated using the Authentication API.

curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/query/relatedContent \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "probe": {
    "title": "Lost Horizon"
  },
  "utcOffset": "-05:00",
  "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
}'

Example request using `documentId`

The following example displays a minimal relatedContent cURL request using documentId.

Replace APPLICATION_ID with your Application ID. Replace ACCESS_TOKEN with the access token you generated using the Authentication API.

curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/query/relatedContent \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "probe": {
    "documentId": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731"
  },
  "utcOffset": "-05:00",
  "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa"
}'

Sample response

The minimum response returned is similar for requests using title or documentId, and includes a count of all possible matches as hits.

{
  "queryId" : "fd110486-f168-47c0-a419-1518a4840589",
  "hits" : 9,
  "docs" : [ {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "rank" : 1,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Event Horizon",
      "document.url" : "https://example.com/docs/movies/1519.html"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-fb148491-b39e-46d1-af33-44cd964d8ee0-34049685392290835527739651484332150529",
    "rank" : 2,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Lost in Space",
      "document.url" : "https://example.com/docs/movies/1725.html"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-118109e5-7ec5-42bb-834d-e3cd41bba65f-47402309926353658638499384569395150502",
    "rank" : 3,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "The Lost Weekend",
      "document.url" : "https://example.com/docs/movies/1830.html"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-d439fd0d-1edf-4982-b00c-51c94a5c0490-43870931094300738494010378876873965115",
    "rank" : 4,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Lost Highway",
      "document.url" : "https://example.com/docs/movies/1408.html"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-1af001c0-cabc-4430-b3b1-c1d8f632e87a-34049685392290835527739651484332150529",
    "rank" : 5,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Raiders of the Lost Ark",
      "document.url" : "https://example.com/docs/movies/1157.html"
    }
  } ]
}

Advanced search request

The following request using title includes all possible fields. This includes an example custom metadata tag, page.metatags.rating, which is requested as a value of the fieldList parameter.

Example request using `title`

curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/query/relatedContent \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
 "probe": {
    "title": "Lost Horizon",
    "description": "Paradise"
  },
  "utcOffset": "-05:00",
  "fieldList": [
    "document.url", "document.title", "document.description", "document.sourceLastModifiedTimestamp", "page.metatags.rating"
  ],
  "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
  "limit": 5,
  "source": "https://example.com/docs/movies",
  "analyticsData": true
}'

Example request using `documentId`

The following request using documentId includes all possible fields. This includes an example custom metadata tag, page.metatags.rating, which is requested as a value of the fieldList parameter.

curl --request POST \
  --url https://APPLICATION_ID.applications.lucidworks.com/query/relatedContent \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
 "probe": {
    "documentId": "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731"
  },
  "utcOffset": "-05:00",
  "fieldList": [
    "document.url", "document.title", "document.description", "document.sourceLastModifiedTimestamp", "page.metatags.rating"
  ],
  "sessionId": "864782f0-af36-4dee-8430-9e73d6006eaa",
  "limit": 5,
  "source": "https://example.com/docs/movies",
  "analyticsData": true
 }
}'

Sample response

The response returned is similar for requests using title or documentId. Five results were returned because the request contained "limit": 5.

{
  "queryId" : "fd110486-f168-47c0-a419-1518a4840589",
  "hits" : 9,
  "docs" : [ {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-6a092bd4-5098-466c-94aa-40bf68294303-68708807657148371333355819934570439731",
    "rank" : 1,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Paradise Road",
      "document.url" : "https://example.com/docs/movies/1443.html",
      "document.sourceLastModifiedTimestamp" : "2022-01-31T19:37:18Z",
      "page.metatags.rating": "3.4"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-fb148491-b39e-46d1-af33-44cd964d8ee0-34049685392290835527739651484332150529",
    "rank" : 2,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Event Horizon",
      "document.url" : "https://example.com/docs/movies/1519.html",
      "document.sourceLastModifiedTimestamp" : "2022-01-31T19:38:04Z",
      "page.metatags.rating": "3.3"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-118109e5-7ec5-42bb-834d-e3cd41bba65f-47402309926353658638499384569395150502",
    "rank" : 3,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Lost in Space",
      "document.url" : "https://example.com/docs/movies/1725.html",
      "document.sourceLastModifiedTimestamp" : "2022-01-31T19:41:23Z",
      "page.metatags.rating": "2.6"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-d439fd0d-1edf-4982-b00c-51c94a5c0490-43870931094300738494010378876873965115",
    "rank" : 4,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Ruby in Paradise",
      "document.url" : "https://example.com/docs/movies/519.html",
      "document.sourceLastModifiedTimestamp" : "2022-01-31T19:32:45Z",
      "page.metatags.rating": "3.5"
    }
  }, {
    "type" : "page",
    "id" : "441eb3be-7de6-470a-8141-e416a15c7db1-1af001c0-cabc-4430-b3b1-c1d8f632e87a-34049685392290835527739651484332150529",
    "rank" : 5,
    "datasourceLabels" : [ "movies" ],
    "fields" : {
      "document.title" : "Exit to Eden",
      "document.url" : "https://example.com/docs/movies/231.html",
      "document.sourceLastModifiedTimestamp" : "2022-01-31T19:28:22Z",
      "page.metatags.rating": "2.1"
    }
  } ]
}

Return only specified fields

Use fieldList to only return the fields that you specify. For example, to see a document’s title in the response but not the URL or other fields, use "fieldList": ["document.title"].

Analytics data

By default, analyticsData is set to true and the request is included in analytical data. If you are testing a request and do not want it to appear in your analytical data, use "analyticsData": false.