--- title: Recommendations API description: Using the WP Engine Smart Search Recommendations API url: https://developers.wpengine.com/docs/smart-search/graphql-api/recommendations/ image: https://developers.wpengine.com/og/docs/smart-search/graphql-api/recommendations.png --- # Recommendations API This API provides document recommendations based on either the gathered data for the site or user provided data. > **Do you have the WP Engine Smart Search Hybrid addon yet?** > > The following example assumes you already have the WP Engine Smart Search Hybrid addon. ## 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. Provide this value to return documents from a specific site only. Omit it to return documents from all sites. - `from`: include documents from this date - `to`: include documents up to this date > **Note** > > Currently, searches are stored for only 7 days. ```graphql query TrendingDocuments { recommendations(count: 2) trendingDocuments(from: "7 days ago", to: "Now") { docID count source } } ``` sample response: ```json { "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. Provide this value to return documents from a specific site only. Omit it to return documents from all sites. - `docID`: the ID of the source document used as the reference point for finding related content. - `useTrendingBy`: optional object that controls whether trending data influences related document ranking. If omitted, no trending boost is applied. - `boost` (Boolean, default: true): when true, documents that are currently trending are ranked higher in the related results. - `minScore`: the minimum score that a document must have to be returned ```graphql query RelatedDocuments { recommendations(count: 2) { relatedDocuments( docID: "post:28" useTrendingBy: { boost: true } minScore: 0.5 ) { docID score source } } } ``` ```json { "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 ```graphql query TrendingDocumentsBySite { recommendations(count: 2, site: "2") { trendingDocuments(from: "7 days ago", to: "Now") { docID count source } } } ``` #### Related documents for a specific site ```graphql 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. ```graphql 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. ```graphql 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. ```graphql 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) ## Was this helpful? Thanks for the feedback! ```json {"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]} ```