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 to return
• site (optional): the WordPress Multisite site ID; when provided, only documents from that site are returned; when omitted, documents from all sites are 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 to return
• site (optional): the WordPress Multisite site ID; when provided, only documents from that site are returned; when omitted, documents from all sites are returned
• docID: the document ID to get related documents for
• 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"
          }
        }
      ]
    }
  }
}

Multisite

On WordPress Multisite installations, use the site argument on recommendations to scope results to a specific site of a multisite. Pass the site ID (for example, 2 to get recommended documents for that specific site).

Trending documents for a specific site

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

Related documents for a specific site

query RelatedDocumentsBySite {
  recommendations(count: 2, site: "2") {
    relatedDocuments(
      docID: "post:28"
      useTrendingBy: { boost: true }
      minScore: 0.5
    ) {
      docID
      score
      source
    }
  }
}

---

Tracker API

The Tracker API enables data collection for user interactions to improve search recommendations and analytics. It provides mutations to track page views, search queries, and search result clicks.

Authentication

Similar to the Recommendations API, a valid authentication token is required in all client requests.

Authorization: Bearer {ACCESS_TOKEN}

Mutations

Track Page View

Records when a user views a page or document.

mutation TrackPageView {
  tracker {
    trackPageView(
      session: { id: "session-123", country: "US" }
      userID: "user-456"
      data: {
        documentID: "post:16"
        page: {
          title: "George the rabbit"
          referrer: "https://example.com/search"
          url: "https://example.com/posts/george-the-rabbit"
        }
      }
    ) {
      success
      message
    }
  }
}

Track Search Query

Records search queries performed by users.

mutation TrackSearch {
  tracker {
    trackSearch(
      session: { id: "session-123", country: "US" }
      userID: "user-456"
      data: {
        search: {
          query: "rabbit care"
          filters: [{ filterName: "post_type", items: ["post", "page"] }]
          sort: { name: "relevance" }
          results: {
            total: 5
            items: [
              {
                documentID: "post:16"
                page: {
                  title: "George the rabbit"
                  referrer: ""
                  url: "https://example.com/posts/george-the-rabbit"
                }
              }
            ]
          }
        }
      }
    ) {
      success
      message
    }
  }
}

Track Search Click

Records when a user clicks on a search result.

mutation TrackSearchClick {
  tracker {
    trackSearchClick(
      session: { id: "session-123", country: "US" }
      userID: "user-456"
      data: {
        documentID: "post:16"
        page: {
          title: "George the rabbit"
          referrer: "https://example.com/search"
          url: "https://example.com/posts/george-the-rabbit"
        }
        search: {
          query: "rabbit care"
          filters: [{ filterName: "post_type", items: ["post"] }]
          sort: { name: "relevance" }
        }
        position: 1
      }
    ) {
      success
      message
    }
  }
}

Data Collection Flow

The typical flow for implementing tracking:

1. Page Load: Use trackPageView when a user lands on a page
2. Search Query: Use trackSearch when a user performs a search
3. Result Click: Use trackSearchClick when a user clicks on a search result

Data Types

Field	Type	Required	Description
session.id	String	Yes	Unique session identifier
session.country	String	No	User’s country code (e.g., “US”)
userID	String	Yes	Anonymous user identifier
documentID	String	Yes	Unique document identifier
page.title	String	Yes	Page title
page.referrer	String	Yes	Referring page URL
page.url	String	Yes	Current page URL
position	Number	No	Position of the clicked result (for search clicks)

Best Practices

• Use consistent userID and session.id values across requests for the same user/session
• Include all available search context (filters, sort, results) for better analytics
• Track interactions in real-time for the most accurate data
• Session IDs should be regenerated periodically (recommended: 30 minutes)
• User IDs should persist longer for better personalization (recommended: 24 hours)