Recommendations API

Do you have the WP Engine Smart Search Hybrid addon yet?

The following example assumes you already have WP Engine Smart Search Hybrid addon.

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

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}

Cookie-Based Data Collection

Recommendations uses cookies to collect non-identifiable data to enhance user experience through personalized recommendations. Below is a detailed overview of the cookies we use and how the data is handled.

Collected Data

Cookie Name	Description	Lifespan	Purpose
user_id	Anonymous identifier assigned to a user	24 hours	Personalization across multiple sessions
session_id	Anonymous identifier for a browsing session	30 minutes	Session-level tracking and insights

Purpose of Data Collection

• Personalized Recommendations:
  We use user_id and session_id to customize content based on user behavior and interaction history.

• Trending Content Insights:
  Aggregated data from session activity helps us identify and surface trending content to users in real time.

• Non-identifiable Usage:
  All identifiers are anonymized and do not contain or infer personal information.

Privacy & Compliance

• No personally identifiable information is collected.
• Data is used strictly for on-site personalization and analytics.
• We do not share this data with third parties.

---

Examples

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"
          }
        },
      ]
    }
  }
}

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"
          }
        },
      ]
    }
  }
}