Thank you for choosing bitREC as your recommender system provider.

This is bitREC’s API documentation. Please read this document carefully to smooth the integration process. In case you would need support or more information, do not hesitate to contact our helpful technicians 24x7: support@bitrec.com.

We suggest that you start by reading a couple of use cases which cover some of the most common situations, platfroms and available data sources.

A typical integration process starts with the upload of metadata as well as historical behavioral information, if available. To get the recommendations you have to call designated endpoints by supplying user IDs and other contextual parameters.

To minimize your efforts metadata can be structured in various formats. We will take care of analyzing the data. Moreover, we can connect directly to your data sources and collect the data on our own.

Use Case 1: Broadcaster with catch-up service on the website

In ‘Use case 1’ broadcaster operates a catch-up website without user login (visitors are tracked by cookies only) as well as streams two live channels. Website displays personalized recommendation blocks on the home page and under the video in the player page. The broadcaster only has some basic metadata in the catalog and does not store any user behavior information that could be supplied to bitREC. In this case bitREC would start gathering behavioral information only from the day of integration. At the beginning recommendations would rely more on meta information and eventually would shift towards behavior based recommendations as more user engagement data is collected.

The integration how-to for this scenario is provided below. You have to start with data upload to supply us metadata and then get recommendations using home and video endpoints for home page and player pages accordingly. Please note that since users are only identified by cookies, cookie ID value should be supplied to the visitorId parameter.

Data Upload

POST /tv1-services/data/items  HTTP/1.1
Host: goldfish.bitrec.com
Authorization: Basic ...
Content-Type: application/json

[
  {
    "itemId" : "item123",
    "categories": ["news"],
    "name": "News",
    "airTime": "2016-12-01 21:00",
    "duration": 302
  },
  {
    "itemId" : "item456",
    "categories": ["talk-show"],
    "name": "Generic Talk Show, Episode 10",
    "airTime": "2016-12-02 15:30",
    "duration": 1851
  }
]

In 'Use case 1’ he provider uploads data is about videos in their library using items endpoint.

itemId is the ID that will appear in our generated recomendations.

categories contains identifiers which helps us group episodes by show.

name, airTime and duration (seconds) are metadata which help us build better recommendation models.

Home Page

GET /tv1-services/recommenations/home?visitorId=123&k=4&userAgent=Mozilla...&ipAddress=123.345.567.789&referer=facebook.com  HTTP/1.1
Host: goldfish.bitrec.com
Authorization: Basic ...

Response:

["item432", "item268", "item7562", "item126"]

home endpoint is used to add a personalized recommendation block on the home page. The recommendations are based on recent viewing history of the user.

visitorId identifies the user viewing the page, usually by cookie ID.

k is the number of recommendations that need to be generated.

userAgent, which identifies the device on which the website is viewed, ipAddress, which helps us figure out the user’s physical location, and referer, which helps us understand how the user navigates the website, are additional contexts that help us make the recommendations more relevant to the user.

Player Page

GET /tv1-services/recommenations/video?visitorId=123&itemId=item456&k=4&userAgent=Mozilla...&ipAddress=123.345.567.789&referer=tv1.com  HTTP/1.1
Host: goldfish.bitrec.com
Authorization: Basic ...

Response:

["item432", "item268", "item7562", "item126"]

video endpoint is used to recommend videos related to the one the user is currently viewing as well as the user’s watching history.

itemId identifies which video is currently viewed.

visitorId, k, userAgent, ipAddress, referer are the same as for home recommendations.

Use Case 2: VOD provider with website and mobile applications

'Use case 2’ applies to a VOD operator which provides services via website and mobile applications. Provider’s services are available for subscribed (users with login) and anonymous users. Subscribers may receive occasional push notifications with content recommendations.

Data Upload

The operator does not use our data upload API. Instead, they provide us with regular XML data dumps.

Recommendations

GET /tv2-services/recommenations/home?visitorId=123&k=4&userAgent=Mozilla...  HTTP/1.1
Host: eel.bitrec.com
Authorization: Basic ...

GET /tv2-services/recommenations/home?visitorId=123&customerId=456&k=4&userAgent=Mozilla...  HTTP/1.1
Host: eel.bitrec.com
Authorization: Basic ...

GET /tv2-services/recommenations/home?visitorId=789&customerId=456&k=4&device=mobile  HTTP/1.1
Host: eel.bitrec.com
Authorization: Basic ...

Response:

["item432", "item268", "item7562", "item126"]

The operator uses home recommendation endpoint. The parameters passed to this endpoint depend on the platform and the user.

Anonymous website users are identified by a cookie-based visitorId. Logged-in web users in addition to cookie-based visitorId also have a customerId which corresponds with users stored in operator’s database. On the web we also get userAgent.

Like on the web, app users may be anonymous and thus visitorId is supplied, or they may be loged-in thus both visitorId and customerId may be provided. If this particular customerId has been using the website, we are able to do cross-device recommendations, and even base them on viewing history before the user has logged-in, connecting his multiple visitorId on various devices. On the app we are not provided with a userAgent parameter, but we receive device parameter instead.

Push

GET /tv2-services/recommenations/push?k=3  HTTP/1.1
Host: eel.bitrec.com
Authorization: Basic ...

Response:

[
  {
    "customerId": "123",
    "recommendations": ["item123", "item456", "item789"]
  },
  {
    "customerId": "456",
    "recommendations": ["item147", "item258", "item369"]
  }
]

The operator also uses push endpoint to generate personalized recommendations for subscribed users to encourage them to consume more content. Push notifications are later generated and sent using the operator’s content pushing services.

Use Case 3: Pay-TV provider with set-top boxes

'Use case 3’ defines a pay-TV service provider with linear and on-demand content offering. The provider has different types of content: a) linear channels b) catch-up TV c) sVOD or tVOD content. The provider also offers different payment tiers (eg. Basic, Extended, Mini etc.)

Data Upload: Items

POST /tv3-services/data/items  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...
Content-Type: application/json

[
  {
    "itemId" : "ch123",
    "categories": ["channel"],
    "name": "Channel 4",
    "plan": "basic"
  },
  {
    "itemId" : "mov456",
    "categories": ["movie", "drama"],
    "name": "Generic Movie",
    "price": 2.9
  },
  {
    "itemId" : "ep789",
    "categories": ["linear", "talk-show", "ch123"],
    "name": "Generic Talk Show, Episode 11",
    "airTime": "2016-12-02 15:30"
  }
]

All of the items are uploaded on items endpoint, however, the attributes of each item differ.

TV channels are identified by "channel" category. They also have a name attribute. plan identifies how channels are bundled into packages.

Movies are identified by "movie" category. price is provided in Euros. Other categories, name are metadata. We are able to get more metadata by mapping name to IMDB or other metadata providers.

Linear TV shows are identified by "linear" category. Shows are associated with their channels by including channel id among categories.

Data Upload: Customers

POST /tv3-services/data/customers  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...
Content-Type: application/json

[
  {
    "customerId": "123",
    "gender": "female",
    "location": "London",
    "age": 33,
    "plans": ["basic"]
  }
]

Additional data about the users is uploaded using customers endpoint. gender, location and age are additional contexts that help us better personalize our recommendations. plans indicate which channel packages are enabled for this user.

Recommendations Screen

GET /tv3-services/recommenations/vod?customerId=123&k=4  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...

GET /tv3-services/recommenations/vod?customerId=123&k=4&filters=drama  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...

Response:

["mov432", "mov268", "mov7562", "mov126"]

GET /tv3-services/recommenations/linear?customerId=123&k=4  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...

Response:

["ep432", "ep268", "ep7562", "ep126"]

GET /tv3-services/recommenations/vod?customerId=123&k=2  HTTP/1.1
Host: cod.bitrec.com
Authorization: Basic ...

Response:

["ch123", "ch456"]

This provider has multiple rows of recommendations on their home screen.

First they use vod endpoint to recommend movies.

Next they use vod endpoint with filter parameter to promote a particular category of videos in a personalized way. For example they have a few dozen of dramas and we pick out 4 that suit this customer the most.

Next they use linear endpoint to recommend linear TV shows.

Finally they use channels endpoint to recommend channels that this user might be interested in, but does not yet have access to via his subscription plan.

Use Case 4: JavaScript integration

In 'Use Case 4’, provider operates a single content platform via website.

GET /tv4-services/recommenations/script.js  HTTP/1.1
Host: carp.bitrec.com

They use our script.js endpoint, which returns a JavaScript file built specifically for the provider. The script then recognizes which page it has been called from and displays the recommendation blocks required. This endpoint is accessible without any authorization. It should be included in the HTML <script> tag.

This method requires least effort to set up our services as we both gather all the available information on the page and also provide the recommendation blocks afer agreeing with you on their design.

Generic Recommendations API

HTTP Request

GET https://<subdomain>.bitrec.com/<client>-services/recommendations/<endpoint>

HTTP Basic authentication is required to access all endpoints, unless otherwise specified.

Parameters

<subdomain> and <client> are constant strings different for each of our clients.

<endpoint> is a string indicating the kind of recommendations required.

The request can include a number of additional parameters in the query string. Most are optional, some are required only on certain endpoints.

Parameter	Description
k	number of recommendations to retrieve
itemId	identifies the main item in this page
visitorId	identifies the current user (unauthenticated)
customerId	identifies the current user (authenticated)
filters	comma separated list of filters restrincting what items can appear in this recommendation block (some filters will be applied by default on some endpoints)
<other>	we can accept additional parameters that either give us better context (such as `location`, `ipAddress`, `userAgent`, `device`) or help us understand user behavior (such as `referer`)

Response

Code	Description
200	Request was successfully completed. Returns results depending on `<endpoint>`
400	Bad request - most likely due to invalid parameter values
500	Internal server error

Generic Data Upload API

It is sometimes preferable to accept data in a different format provided by the client, in order to make use of all the data available. As long as we agree on what values itemId, customerId and filters can take, this is not a problem.

To make sure the recommendations are relevant, modified objects should be reuploaded soon.

HTTP Request

POST https://<subdomain>.bitrec.com/<client>-services/data/items

POST https://<subdomain>.bitrec.com/<client>-services/data/customers

HTTP Basic authentication is required to upload data.

The data objects to be uploaded need to be provided as a JSON list in the body of the request.

Response

Code	Description
200	Request was successfully completed
400	Bad request - most likely due to invalid parameter values
500	Internal server error

Response body is empty.

Items

items represent objects that can be recommended.

Parameter	Description
`itemId`	corresponds with the `itemId` parameter in recommendation endpoints as well as the IDs returned by our recommender
`categories`	corresponds with the `filters` parameter in recommendation endpoints as well as any additional classification such as the type of this item. Heirarchical relationships between items are also specified as categories.
`<other>`	additional values can be supplied, such as metadata (`name`, `description`, `airTime`, `duration`) or pricing information (`price`, `discount`, `plans`), that we could analyze to build better recommendations

Customers

customers represents the registered users of your service. Uploading customer information is not necessary, however it allows us to use many additional contexts to improve the quality of our recommendations.

Parameter	Description
`customerId`	corresponds with the `customerId` parameter in recommendation endpoints
`<other>`	additional values, such as `location`, `age`, `gender`, that we could analyze to build better recommendations