Marfeel Recommender API for push, email, and infinite scroll

The Marfeel Recommender API returns personalized article recommendations in JSON format, without rendering HTML. Use it to power push notifications, newsletters, or infinite scroll with content tailored to each user.

The API endpoint is https://experiences.mrf.io/recommenderexperience/render.json.

Before using this API, you will need to create a recommender experience using Marfeel Experience Manager, or via API, so that you can configure your recommendation engine along all its other available parameters.

Query parameters

The endpoint accepts the following query parameters:

• id: the id of the recommender, which you can obtain from the url when accessing the experience in Experience Manager. This value is mandatory.
• canonical_url: the url that you want recommended content to be similar to.
• domain: the domain of your website. Only mandatory if canonical_urlis not provided.
• client_id: Marfeel’s id of the user you want to send recommendations to. Not mandatory, but needed for personalization of the recommendations.

You can obtain any user Id using Marfeel SDK's getUserId method:

<script>
window.marfeel.cmd.push(['compass', function(compass) {
  compass.getUserId().userIdPromise).then(
           (userid) =>  // do something ;
    )
}]);
</script>

If you are sending your own user ids to Marfeel using our User Subscriber functionality, you can directly use these same ids (subscriber ids) to get recommendations. You can also request any subscriber id from Marfeel SDK method compass.getSiteUserId().

Request example:

curl -G https://experiences.mrf.io/recommenderexperience/render.json \
  -d id=IL_rq6St2-fT2KNWFE8X1cwSQ \
  -d domain=touch.marfeel.com \
  -d client_id=dd1da57f-6fe1-4770-96cf-4b853a5990b1

Response format

Each request returns an array of recommendations in JSON format. Every recommendation includes the following fields:

• url: The canonical url of the recommended article (string)
• title: The title of the recommended article (string)
• img: Main image of the recommended article (string)
• authors: an array containing all author names for the recommended article (array of strings)
• sections: an array containing all section names for the recommended article (array of strings)
• publishTime: the publication date of the recommended article (string, date format yyyy-MM-dd hh:mm:ss)

All values are obtained from Marfeel’s analytics platform and are extracted as described here.

Response example

{
  "type":"RecommenderExperienceResponse",
  "recommendation":[
    {
      "url":"https://touch.marfeel.com/resources/blog/marfeels-response-to-confiants-privacy-policy-violation-allegations",
      "title":"Marfeel's Response to Confiant's Privacy Policy Violation Allegations ",
      "img":"https://marfeel.anticipa.io/public/uploads/default/image/blog/02_02_2022_12_15_08_blog_post_.jpeg",
      "authors":["Jon Doe"],
      "sections":["Audience", "Blog"],
      "publishTime":"2022-02-01 00:00:00"
    }
  ]
}

Get recommendations from SDK

For use cases such as rendering recommendations client side or adding pages in an infinite scroll feed, the Marfeel SDK provides a dedicated method that returns the same data without a direct API call.

Insert the following script in your HTML:

window.marfeel.cmd.push(['experiences', (experiences) => {
  experiences.getRecommendations('<experience_id>') // insert your experience id here
    .then(recommendations => {
               // do something with recommendations
    });
  }]);

The recommendations array follows the same structure as the recommendation field in the API response above.

[
  {
    "url":"https://touch.marfeel.com/resources/blog/marfeels-response-to-confiants-privacy-policy-violation-allegations",
    "title":"Marfeel's Response to Confiant's Privacy Policy Violation Allegations ",
    "img":"https://marfeel.anticipa.io/public/uploads/default/image/blog/02_02_2022_12_15_08_blog_post_.jpeg",
    "authors":["Jon Doe"],
    "sections":["Audience", "Blog"],
    "publishTime":"2022-02-01 00:00:00"
  }
]