Skip to content
Headless Platform

Recommendations API

This API provides document recommendations based on either the gathered data for the site or user provided data. Note: This API is in BETA

Authentication

Section titled “Authentication”

Clients calling the API are required to add an authentication header with the valid authentication token. This token can be retrieved from the Smart Search Plugin Settings.

Authorization: Bearer {ACCESS_TOKEN}

Examples

Section titled “Examples”
Section titled “Trending documents”

The recommendations API utilizes collected site data, specifically search data, to generate a list of frequently searched documents.

Input Parameters:

  • count: the number of documents that will be returned
  • from: include documents from this date
  • to: include documents up to this date

Note: Only 7 days of searches is stored currently.

query TrendingDocuments {
  recommendations(count: 2)
    trendingDocuments(from: "7 days ago", to: "Now"){
        docID
        count
        source
    }
}

sample response:

{
  "data": {
    "recommendations": {
        "trendingDocuments": [
            {
                "docID": "post:16",
                "count": 7,
                "source": {
                    "ID": 1,
                    "post_content": "Rabbit is happily running",
                    "post_date": "11-06-2023T12:33:00",
                    "post_status": "publish",
                    "post_title": "George the rabbit",
                    "post_type": "rabbit"
                }
        },
         {
            "docID": "post:21",
            "count": 6,
            "source": {
                "ID": 2,
                "post_content": "Horse in a field",
                "post_date": "11-06-2023T12:33:00",
                "post_status": "publish",
                "post_title": "Greg the horse",
                "post_type": "horse"
          }
        },
      ]
    }
  }
}
Section titled “Related Documents”

The recommendations API provides related documents to a user-provided document by using our AI vector search. Additionally, trending documents can be boosted in the results.

Input Parameters:

  • count: the number of documents that will be returned
  • docID: the document ID to get related documents to
  • useTrendingBy:
    • boost: boost the trending documents in the related results (if any)
  • minScore: the minimum score that a document must have to be returned
query RelatedDocuments
{
    recommendations(count: 2){
        relatedDocuments(docID: "post:28", useTrendingBy: {boost: true}, minScore: 0.5){
            docID
            score
            source
        }
    }
}
{
  "data": {
    "recommendations": {
        "trendingDocuments": [
            {
                "docID": "post:16",
                "score": 0.9,
                "source": {
                    "ID": 1,
                    "post_content": "Rabbit is happily running",
                    "post_date": "11-06-2023T12:33:00",
                    "post_status": "publish",
                    "post_title": "George the rabbit",
                    "post_type": "rabbit"
                }
        },
         {
            "docID": "post:21",
            "score": 0.8,
            "source": {
                "ID": 2,
                "post_content": "Horse in a field",
                "post_date": "11-06-2023T12:33:00",
                "post_status": "publish",
                "post_title": "Greg the horse",
                "post_type": "horse"
          }
        },
      ]
    }
  }
}