API Guide

Stepping through Bibblio's API

Step 1 - Decide on your implementation features

We’re always around to assist you with your API integration, but find some pointers below to guide your implementation.


Installing our assets

The easiest way to use the module is via our CDN. There is no need to install anything since the assets can be retrieved directly from Bibblio's servers.

However, you might be used to NPM and Bower for all your third-party content. To host the module on your side, follow our instructions to download our Bower and NPM packages.


Content type

We use only text to generate recommendations. The recommendations’ quality improves with a content item’s length, but a few words is usually all it takes. Therefore if you are planning on sending us different types of content items make sure there is at least a title or a short excerpt in the content body so we can process it.


Content volume

How much of your historic content do you want to import to Bibblio? If you are a news publisher, you might not want to recommend articles dating back ten years. We have a recency feature that gives a boost to recently published items, so you could always be serving fresh recommendations on older content. All content added will go towards your storage count, so make sure you are sending us a number of content items that matches your plan.


Content grouping

You can use our catalogue feature to separate your content into groups. This is helpful if you have different types of content that shouldn’t appear in the same widget, like different language versions of the same article, or if you want to promote specific content. When retrieving recommendations, it is possible to request the catalogue or catalogues from which to draw content items.

A few things to keep in mind:

  • When deciding on a number of catalogues, it’s helpful to reflect on what you want to achieve with the grouping. There is no need to create one catalogue per category on your site if you plan on recommending them all in the same module (that’s what the algorithm is here for!). On the other hand, you might want one widget showing “Popular videos” on your article pages.

  • Content items can only be in one catalogue at a time.

  • To move an item from one catalogue to another, you will have to update that content item via the API.


Content attributes

When importing your content to Bibblio, you can provide us with a set of field names mapped directly to your own data. We only require three in order to process your content: name, text, url.

We strongly recommend you add an image in moduleImage, and the datePublished if you are planning on using our recency parameter. A little excerpt of the article in description is also a nice-to-have if you’re planning on giving more information to the user when they hover over a recommendation on our module.

The rest is entirely up to you and will depend on your internal taxonomy. Most of our API users supply a customUniqueIdentifier to match our content items to their internal blueprint.


Using Bibblio’s pre-built modules vs creating your own

We recommend using our elegantly designed modules that are ready to go and fully customizable, for a faster installation. You can use CSS to override our style classes and make it match your site’s design. We track user behaviour and generate analytics stats through these modules, meaning you will immediately get visibility over the module’s performance from the moment it is live on your page.

For an overview of the module’s different layouts, try our module builder.

You can also choose to directly plug in to the API to retrieve the recommendations and build your own module.  you will however need to send us tracking events in order to benefit from the machine learning. You will need to set viewed events and send us everything via our tracking endpoint.


A/B Testing

Bibblio generates behavior-optimized recommendations by default, served on our standard endpoint. There is an initial learning phase, in which our algorithm will make predictions and adapt the recommendations according to user interaction data.

If you are setting up an A/B test over a few days, we recommend retrieving recommendations from our non-optimised endpoint. This will avoid any “cold start” issues with the algorithm. We will still be collecting interaction data in the meantime so you can easily revert to our optimised endpoint afterwards.


Device type

Bibblio’s recommendation module scales beautifully across all devices. If a large portion of your traffic comes from mobile, we would recommend placing a module below your articles rather than a sidebar. Sidebar modules will still render at the bottom of your page.

Bibblio is also compatible with Google AMP using our AMP snippet.

Step 2 - Retrieve your credentials from your Bibblio account

Get you Client Id and Client Secret from your Bibblio account. These will provide a secure way to identify yourself when connecting to the API.

You can find these in your Bibblio credentials page.

Step 3 - Import your content

Send your content to Bibblio by making a POST request to our API at https://api.bibblio.org/v1/content-items. All content items need to be formatted as valid JSON with a maximum size of 200 KB.

Make sure you supply a customUniqueIdentifier to easily retrieve recommendations later on. Otherwise, you will have to store the Bibblio contentItemId we generate for each content item.

You can expect the response times for content item ingestions to take between 150ms and 1000ms on average.

There should ideally be an initial bulk import of your existing content, followed by automated, continuous imports on publication.

Step 4 - Wait for your first batch indexing

Your content items will become available in the “Content” section of your Bibblio dashboard before the indexing is complete. To see whether we’ve generated recommendations for an item, simply click on it and the recommendations should appear on the right hand side panel.

Indexing time will vary depending on the size of your corpus and the depth of your content items. For a corpus of 100,000 items of a relatively shallow size (articles, blog posts, etc,) you should expect your first indexing job to take up to 1 hour 20 minutes. After this initial indexing, continuously stream new content coming in, so there will not be any waiting time, even on freshly published articles.

Step 5 - Retrieve recommendations

Once your content has been imported and recommendations have been generated, you can retrieve them using a Recommendation Key. A Bibblio Recommendation Key is an authorization token linked to your account that is safe to use on your site and does not need to be regenerated for every request. You can find your Recommendation Key on the Credentials page.

Step 6 - Set up tracking

Your Bibblio dashboard gives you access to monthly stats for your module: click-through rate, in-view click-through rate, the number of clicks and pages served on your site. For a more granular monitoring of your Bibblio audience, you can add utm tracking parameters to our module.

If you built your own module, you will have to send us the recommendation events via our tracking endpoint.


If you're having difficulties with your API implementation, please check out our FAQ and full documentation.