Site Optimization API

  • Updated

Site Optimization is a licensed part of the Engagement solution that will automatically recommend the right, high-value content and goal pages for each visitor using Artificial Intelligence and machine learning to increase engagement and accelerate the path to conversion.

The Site Optimization API is responsible for serving the recommendations that fill the site optimization recommendation window.

NOTE: Keep in mind that implementing a custom API solution involves a significant amount of work for your team. For faster, more efficient implementation we highly recommend that you instead use our standard integration via Demandbase Tag.

Prerequisites

  • The Demandbase Tag must have been live on the website where recommendations are being made for more than 2 weeks. The model will be trained after tens and thousands of page views. If you need help installing your Demandbase Tag please contact your CSM or our technical support team at support@demandbase.com.
  • You must use your Demandbase Tag API Key for the Site Optimization API. This is found in the Network request when Demandbase Tag runs on your website. mceclip0.png
  • The Site Optimization model must have been successfully run. To check if it runs successfully you should see recommendations in the preview step of the Site Optimization product. If you are getting an error related to this, please contact support@demandbase.com.

Example Request

The are 3 main parameters:

  1. The Demandbase SID (Demandbase company ID from the Company API)
  2. The base64 encoded Page URL
  3. Your Demandbase Tag API Key

Example URL:

The three main parameters are highlighted in yellow.

https://site-optimization-api.company-target.com/recommend/ 1234566 ?page= aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v &apiKey= alphanumerickey123

Example Response

//HTTP 200
 
{
  "rid": "jf5haxntTJmTVPpILEYTJw",
  "should_display": true, 
  "recommendations": [
    {
      "page": "www.demandbase.com/ebook/account-based-marketing-the-key-to-b2b-success?db-siteopt-rid=jf5haxntTJmTVPpILEYTJw",
      "image": "https://www.demandbase.com/wp-content/uploads/resources-thumbnail-ebook-generic-image.jpg",
      "title": "Account-Based Marketing: The Key to B2B Success",
      "probability": 0.061109114708916126,
      "expected_value": 2.418023084591552,
      "score": 0.14776325004511234,
      "conversion_pages": [
        {
          "conversion_page": "www.demandbase.com/ebook/account-based-marketing-the-key-to-b2b-success",
          "prob_current": 0.043516029510918625,
          "prob_next": 1.0452581939500543,
          "prob_increase_percentage": 2302
        },
        {
          "conversion_page": "www.demandbase.com/ebook/b2b-marketers-guide-account-based-marketing",
          "prob_current": 0.007600901381545576,
          "prob_next": 0.12631249511237413,
          "prob_increase_percentage": 1562
        },
        {
          "conversion_page": "www.demandbase.com/ebook/account-based-marketing-fundamentals-every-b2b-marketer-must-know",
          "prob_current": 0.010444291041493019,
          "prob_next": 0.12118793017898015,
          "prob_increase_percentage": 1060
        }
      ],
      "all_negative": false
    },
    {
      "page": "www.demandbase.com/resources/events?db-siteopt-rid=jf5haxntTJmTVPpILEYTJw",
      "image": "https://www.demandbase.com/wp-content/uploads/default-ebook-webinar-featured-image.jpg",
      "title": "Events & Webinars",
      "probability": 0.08430272903519226,
      "expected_value": 0.802242591154425,
      "score": 0.06763123978258201,
      "conversion_pages": [
        {
          "conversion_page": "www.demandbase.com/webinar/abm-team-sport",
          "prob_current": 0.03336430201557014,
          "prob_next": 0.14394467231724659,
          "prob_increase_percentage": 331
        },
        {
          "conversion_page": "www.demandbase.com/ebook/abm-team-sport",
          "prob_current": 0.015241847022255948,
          "prob_next": 0.06485992385455719,
          "prob_increase_percentage": 326
        },
        {
          "conversion_page": "www.demandbase.com/webinar/abm-impact-blended-approach",
          "prob_current": 0.016828193365295403,
          "prob_next": 0.025558355669193622,
          "prob_increase_percentage": 52
        }
      ],
      "all_negative": false
    }
],
  "sid": 5347713,
  "current_page": "www.demandbase.com",
  "logo": "https://d2b50tjqdt4ebt.cloudfront.net/media/companies/196338",
  "company_name": "Demandbase",
  "pageviews_30": 87,
  "pageviews_60": 148,
  "pageviews_90": 295,
  "pageviews_all": 543,
  "sessions_30": 17,
  "sessions_60": 34,
  "sessions_90": 70,
  "sessions_all": 116
}

 Request Parameters

Name Data Type Description Example
sid Integer This identifies the company, and as an identifier specific to Demandbase. It corresponds to the demandbase_sid response field from the IP API. /recommend/ 5347713 ?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey=3cb1dcb19f551
page String The page for which to serve recommendations. The URL should contain the protocol and it should be base64 encoded. /recommend/5347713?page= aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v &apiKey=3cb1dcb19f551
apiKey String This is your primary Demandbase API key. You can find it in your IP API requests made by Demandbase Tag, and you can also ask us for this value. Ask for your Analytics Enabled API key. /recommend/5347713?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey= 3cb1dcb19f551
solveConversionProbabilities Boolean This value determines whether or not the conversion_pages field will be populated in each recommendation. It is expensive to calculate so we require an explicit request to return it. Default value is false. /recommend/5347713?page=aHR0cHM6Ly93d3cuZGVtYW5kYmFzZS5jb20v&apiKey=3cb1dcb19f551&solveConversionProbabilities= true

Response fields

Top Level Response Object

Name Data Type Description Example
rid String A unique recommendation id that identifies the given instance of recommendations. It is generated for every set of recommendations. "rid": "y1GsZW8wSJ2UMs6WnVUsjw",
should_display Boolean This field determines whether recommendations should be displayed on the current page, or not. It is calculated based on the set of rules, specified in Demandbase setup console (Engagement -> Site Optimization -> Display Options) "should_display": true
recommendations Array[Recommendation Object] The top level collection responsible for holding the group of recommendations "recommendations": [{...}]
sid Integer See request parameters. It will always be the same as this value. "sid": 3415304,
current_page String The page for which we are serving recommendations. This will be a standardized version of the "page" request parameter. The protocol and query string are removed. "current_page": "www.demandbase.com"
logo String A URL to the logo we have identified for the company identified by the sid request parameter. "logo": "https://d2b50tjqdt4ebt.cloudfront.net/media/companies/196338",
company_name String The name of the company identified by the sid request parameter "company_name": "Demandbase"

 

Recommendation Object

Name
Data Type
Description
Example
page String A standardized URL that points to the recommended page. The protocol and query string are removed, and db-siteopt-rid will be added for tracking purposes. This identifier is the same as the "rid" response field
"page""www.demandbase.com/ebook/account-based-marketing-the-key-to-b2b-success?db-siteopt-rid=jf5haxntTJmTVPpILEYTJw",
image String A URL that points to the image that best represents the page as determined by our algorithm, which takes many features of the page into consideration.
title String The cleand-up page title. Our algorithm automatiocally removes page title segments that repeat too often, in order to remove common title formats like "Actual Page Title | Company Name". In this example, our cleaned-up page title would be "Actual Page Title".
"title""Account-Based Marketing: The Key to B2B Success",
probability Float The normalized output of the page transition model's score for this recommendation. This value correlates with how likely we believe the user is to visit this page.
"probability": 0.061109114708916126,
expected_value Float The value from the solution of a Bellman equation for a reward vector that gives a terminal reward of 0.1 for regular pages, 0 for blacklist pages, and 1 for conversion pages (see personalization.demandbase.com/setup/pages for these definitions). Due to this definition, it can also loosely be interpreted as the number of conversion pages we expect the user to visit if they visit this page.
"expected_value": 2.418023084591552,
score Float The probability multiplied by the expected_value. This is what determines the default sort order for recommendations.
"score": 0.14776325004511234,
conversion_pages Array[Conversion Page Object] The collection responsible for holding the top 3 conversion pages that relate to the recommended page. It is only populated if solveConversionProbabilities set on the request parameter is true.
"conversion_pages": [
        {...}
]

 

Conversion Page Object

Name
Data Type
Description
Example Use
conversion_page String The standardized conversion page URL
"conversion_page""www.demandbase.com/webinar/abm-team-sport",
prob_current Float A value that correlates to the likelihood that the user visits the given conversion_page given that they are currently viewing the current_page. It is the value as determined by the solution of a Bellman equation for a reward vector where this page is the only page gives any terminal reward (1).
"prob_current": 0.03336430201557014,
prob_next Float A value which correlates to the likelihood that the user visits conversion_page (at any point in their session) given that they are currently viewing the recommended page.
"prob_next": 0.14394467231724659,
prob_increase_percentage Float

Essentially 

(100 * (prob_next - prob_current) / prob_current).round
"prob_increase_percentage": 331
DISCLAIMER: Any apparent response fields that are not described in this document are temporary and for diagnostic purposes. Do not depend on them as they may be removed at any time. Here is an example of such a field: "pageviews_30": 87,

Defensive Coding

API response data attributes will vary. While we will do our best to inform our customers of changes that we believe will impact them, do not code against an exact count of properties in the response or expect all properties at all time, we expect to remove or introduce new properties and your code should handle all scenarios defensively.

Was this article helpful?

0 out of 1 found this helpful