Related Content API

Use the Related Content API to retrieve indexed documents that are similar to a specific indexed document.

Site Search determines related content by comparing terms in the title and description fields configured for the app. Related results also respect applicable Search Profile Data Filters.

Availability And Location

The Related Content API is available for all Site Search apps.

Find the endpoint in App Settings > All APIs > Search & Indexing, between Auto-Suggest API and Smart Answers API.

The endpoint appears in a read-only field. Select Copy to copy the complete endpoint URL.

Select Show Related Content API Example to view a request example generated for your app.

Endpoint

• Method: POST
• Endpoint: Use the complete Related Content API endpoint displayed for your app in App Settings > All APIs > Search & Indexing.

The endpoint uses the /mlt request handler. Copy the complete URL from Site Search instead of constructing the endpoint manually.

Authentication

Authentication depends on the app type.

Shared Apps

Use the app's read-only token:

Authorization: Token <read-only-token>

Dedicated Apps

Use basic authentication with the API username and read-only password for the app.

The generated example in All APIs uses the correct authentication method and app-specific endpoint.

Request Parameters

Document IDs

Pass the document ID directly to q:

q=<doc_id>

Don't add an id: prefix.

A document ID can contain characters that need URL encoding. For example, if your document IDs are URLs, URL-encode the q value when building the request.

Request Examples

These examples use placeholders. You can also copy the generated request for your app from All APIs.

Shared App

curl --location --request POST \
  -H "Authorization: Token <read-only-token>" \
  "<related-content-endpoint>?q=<url-encoded-doc-id>"

Dedicated App

curl --location --request POST \
  -u "<api-username>:<read-only-password>" \
  "<related-content-endpoint>?q=<url-encoded-doc-id>"

To limit the returned fields and results:

curl --location --request POST \
  -u "<api-username>:<read-only-password>" \
  "<related-content-endpoint>?q=<doc-id>&fl=title,description&rows=5"

How Related Content Is Determined

Site Search uses the configured title and description fields to identify documents that contain terms similar to the source document.

The title and description fields used for this comparison come from the metadata mappings configured in Results Fields.

The source document isn't included in its own related-content results.

Data Filters configured in the applicable Search Profile are also applied to related results.

Not every indexed document necessarily has related content. A valid source document can return no matches.

Response

Successful requests use a Solr-style response envelope.

The response object includes:

• numFound — Number of related documents found.
• start — Starting offset of the returned results.
• numFoundExact — Indicates whether numFound is exact.
• docs — Related documents.

The fields in each item in docs follow the app's configured Results Fields unless you override them with fl.

Response Example

The fields returned for your app can differ from this example.

{
  "responseHeader": {
    "status": 0,
    "QTime": 9
  },
  "response": {
    "numFound": 2,
    "start": 0,
    "numFoundExact": true,
    "docs": [
      {
        "id": "https://example.com/content/article-1",
        "url": "https://example.com/content/article-1",
        "title": [
          "Example Related Article"
        ],
        "description": [
          "Example description for a related document."
        ]
      },
      {
        "id": "https://example.com/content/article-2",
        "url": "https://example.com/content/article-2",
        "title": [
          "Another Related Article"
        ],
        "description": [
          "Another example related document."
        ]
      }
    ]
  }
}

No Related Content

A valid source document can exist without having any related matches.

In that case, the API returns a response with numFound set to 0 and an empty docs array:

{
  "responseHeader": {
    "status": 0,
    "QTime": 23
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "numFoundExact": true,
    "docs": []
  }
}

Source Document Not Found

If the document ID doesn't match a document in the index, the response is null:

{
  "responseHeader": {
    "status": 0,
    "QTime": 1
  },
  "response": null
}

This is different from an indexed document that has no related matches.

Pagination

Use rows and start to page through related results.

For example:

?q=<doc_id>&rows=10&start=0

The next page begins at the next offset:

?q=<doc_id>&rows=10&start=10

Advanced Related Content Parameters

Most integrations only need q and, optionally, fl, rows, and start.

The Related Content API also supports parameters that control how similarity is calculated. Requests that exceed the supported limits return an HTTP 400 response.

Note: The app's configured title and description fields are used for related-content matching without requiring these advanced parameters in a typical request.

Request Errors

Requests that exceed a supported Related Content parameter limit return HTTP 400.

If a request fails because of one of these limits, check the affected parameter and keep its value within the supported range.

If authentication fails, verify that you're using the authentication method for your app type:

• Shared apps use the read-only token.
• Dedicated apps use the API username and read-only password.

Shared API Foundations

Use these shared references for authentication, request and response conventions, and pagination:

• Authentication and Authorization
• Request and Response Conventions
• Pagination

Related Articles

• Search & Indexing