liorboord / test Goto Github PK

ola Recommendations REST API  1.2

# Overview

 The Taboola Recommendations API is a public API accessible by externally developed client implementations.
 The API specification is public but access is controlled by using API keys that are registered to specific clients on a per-publisher account. 

The API allows external developers to integrate Taboola recommendations into application running on desktop applications, AJAX web applications, mobile internet devices (“smart phones”, tablet computers, etc.), set-top  boxes, and any other application capable of using a REST API.## 

## Application Implementation Requirements

 The Taboola Recommendations API must be used by applications in accordance with these specifications and
any deviation from these specifications may cause termination of the API key, resulting in the inability of the
 application to access the API. All implementing applications must implement the full specification including
 event logging.

 The following data elements should be requested from Taboola in order to start using the API:
* The publisher id in the Taboola system
* per application API key

###  Application  API keys

Access to the Taboola Recommendations API is governed by per application API keys that are assigned for each application that implements the API.

In case a publisher intends to use the Taboola Recommendations API in several different applications, several different API keys should be generated for each application. Each API key is a globally unique string of hexadecimal characters that is registered by Taboola. Each API key is associated to the publisher account and to the specific application / use case for which it was created. Each key has the following life-cycle:

1. Upon creation  a key is  considered  to  be  a “development” key. Keys in  this  state have  several restrictions, including a concurrency restriction of  a maximum of  5 simultaneous  users,  and a usage restriction of  up to 3,000 daily requests.

2. A  key may then  advance to  the “production” key state. Keys  in  this  state have  no  restrictions  associated  to  them. In  order for a key to  become  a “production” key, the application using it  must  be  validated by  Taboola.  

3. Keys in  any of  the states  may become  “revoked”,  in  cases of  misuse  or  upon  client  request.

###  Transport, Request Origin, Caching and Cookies
The Taboola Recommendations API is implemented as a RESTful protocol using stateless HTTP transactions.

Requests are sent using the GET HTTP method and responses are formatted as a JSON formatted string.  In order for the API to function properly, the API requests must not be cached: every view of a recommendations unit must be generated by its own API request, and that API request must be invoked not more than 30 minutes before the actual rendering of the recommendation module.


###  URL  structure
The Taboola Recommendations API is accessed as a set of HTTP URLs that should be invoked by a conforming HTTP/1.1 client. The URL that the client should use to call the API is formed by using the “base URL” address as the protocol and host name, adding to it the protocol reference version, the expected format for the response, publisher’s id and the method name being called as the path elements and finally adding any arguments that need to be passed to the call as query string parameters. The format of the URL used to call the API is as follows:

``` 
http://api.taboola.com/`<protocol-version>`/`<format>` /`<publisher id in the Taboola system>`/`<method-name> `?`<argument-list>` ```
```
```
<protocol-version> ::= “1. 2 ”
<format> ::= “json”
<method name> ::= “recommendations.multiple-get” | “recommendations.get” | “recommendations.notify-click” |
“recommendations.notify-visible” | “recommendations.notify-available”
<argument-list> ::= <argument> [&<argument>] [&<argument>] ...
<argument> ::= <URL-encoded-argument-name> “=” <URL-encoded-argument-value>
```

Arguments that are objects should be flattened to multiple <object-name>.<attribute-name> arguments. For example, given a response id parameter with the value of 2345112123, and an item id parameter with a value of 678328755932, a call to the API that notifies Taboola of a click event should be formatted in the following manner:

> http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-click ?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&response.id=2345112123&response.ses
sion=skajfoiqwr3209urejf293&item.id=678328755932&item.type=video

###  Error  Handling
Although Taboola servers have fail safe layers that would try to always return recommendations, even in case of server errors, we cannot guarantee a valid response will always be received as the request or response might be blocked because of network conditions. It is strongly encouraged that the application would handle a case where no recommendations are returned to the application within a reasonable time, or when an error response is received. In case an invalid request is sent to the API, Taboola will return one of the following errors:

| HTTP Status Code  | Meaning |
|----------------------|-----------------|
| 400 | Bad Request Invalid publisher, invalid URL path or missing required parameter |
| 401 | Unauthorized Invalid API key |
| 429 | Too Many Requests Rate limit exceeded |
| 5xx | type code An unintended server error has occurred |



## Recommendations API

REST API currently supports 2 types of recommendations requests – Single request and multiple request. Single request means that the recommendations will be presented on one module on the page, whereas multiple request means means presenting recommendations on different modules on on the page.

### Requesting  Recommendations
The application should call the “recommendations.get” method to generate a list of recommendations that will be
 displayed on a single module on the page. The method takes a list of arguments describing the page where the
 recommendations is going to appear, and will return a response identifier that can be later used to send event
 messages pertaining to that list, followed by the list of recommended items.

### recommendations.get 

#### app.type 
|  |  |
|----|------|
| Required | yes |
| Type | String | 

The API key that was provided by Taboola for the application

#### app.apikey 

|  |  |
|----|------|
| Required | no |
| Type | String | 

An optional argument specifying the current application name. Not needed if the application name is added to the user agent (either automatically like in iOS, or manually) 

#### placement.name 
|  |  |
|----|------|
| Required | no |
| Type | String | 

A text string, uniquely identifying the placement of a widget using the recommendations response in the application. If provided, this will allow breaking down reporting, and specifically controlling the recommendations behavior for each placement (similar to Google AdSense custom channels). “source.placement” is supported for backward compatibility For example, if the application uses recommendations on both “articles” and blog posts, “source.type” on both pages would need to be “text”, but the “placement” on the former might be “article” and “blog” on the latter. Another example – if the application places two recommendation modules on the video page, one below the player and one to the right, the placement parameter might be “below player” for the first and “right rail” for the second 

#### placement.rec-count 

|  |  |
|----|------|
| Required | no |
| Type | Integer | 

A non-negative integer specifying how many recommendations are requested. The API will not return more recommendations than this, though if there are not enough good quality recommendations to satisfy the request, fewer items might be returned. “rec.count” is supported for backward compatibility

 #### placement.organic-type

|  |  |
|----|------|
| Required | no |
| Type | String | 


Valid values:

| Value | Details |
|----|----|
 | video  | return only video content ( default )
 | text  | return only textual (stories) content
 | photo | return only photo / galleries content
 | mix  | return a mix of several content types. In case a mix is requested, the exact mix is determined by server side configuration. Different configurations can be used for different source.type and placement parameters.

#### lacement.thumbnail.width
#### placement.thumbnail.height

|  |  |
|----|------|
| Required | no |
| Type | Integers | 

The size (in pixels) of the thumbnails returned for recommendations.
Both parameters (height and width) should either appear together or
not appear at all. In case the thumbnail size parameters are specified, the thumbnail
would always preserve its original aspect ratio – it will be scaled to the
required size, centered and cropped if needed. In addition, in case the thumbnail contains a face, we will detect that face by default and ensure it is contained within the generated
thumbnail.  “rec.thumbnail.width” / “rec.thumbnail.height” are supported for backward compatibility

#### placement.visible 

|  |  |
|----|------|
| Required | no |
| Type | Boolean | 

Indicates whether the recommendations are visible right after the
“recommendations.get” request. Default is “true”
In case this argument is set as “false”, a separate
“recommendations.notify-visible” event should be sent when
the recommendations are actually visible.
“rec.visible” is supported for backward compatibility

#### placement.available

|  |  |
|----|------|
| Required | no |
| Type | Boolean | 

Indicates whether  the recommendations were served right after the
“recommendations.get” request. Default is “true”
In case this argument is set as “false”, a separate
“recommendations.notify-available” event should be sent
when the recommendations are served.
**Recommendations are not allowed to be cached more than 30
minutes!**

#### response.callback 

|  |  |
|----|------|
| Required | True if JSONP response is needed |
| Type | String | 

Specifies the name of the callback function to use in the JSONP style
response. “rec.callback” is supported for backward compatibility

#### source.type 
|  |  |
|----|------|
| Required | True |
| Type | String | 

The type of the content the recommendations will be placed next to.
The following values are supported:


| Value | Details |
|----|----|
 | video  | should be passed when the recommendations are placed near a video
 | text  | should be passed when the recommendations areplaced near a textual piece such as an article / story
 | photo  |  should be passed when the recommendations are placed near a photo or gallery
 | home  |  should be passed when the recommendations are placed on the app entry (home) screen
 | section  | should be passed when the recommendations are placed on a screen representing “section front” or “topic”
 | search  | should be passed when the recommendations are placed on a search results page

#### source.id 
|  |  |
|----|------|
| Required | True |
| Type | String | 

The id of the item for which the recommendations should be provided.
Please consult your Taboola account manager regarding which ID
should be provided here for each type of content

### source.url 
|  |  |
|----|------|
| Required | True |
| Type | String | 

A fully qualified (http:// or https://) publicly accessible URL that
contains the content and/or meta data for the current source item (the
piece of content the recommendations are going to be placed next to).
#### User.session 
|  |  |
|----|------|
| Required | True |
| Type | String | 
Should send either the value “init” for the first request in a session or the session value from the response to the last “recommendations.get” request in the session.
User.referrer Recommended String The referrer (HTTP header) from the request that led to the current page.

#### User.agent
|  |  |
|----|------|
| Required | No |
| Type | String | 

is sent through a server
String The user-agent (HTTP header) from the client side request.

####  User.realip Required if the request

|  |  |
|----|------|
| Required | Yes Required if the request is sent through a server|
| Type | String | 

The real IP address of the client side request. Required in case the
request is sent through a server. Should be formatted as dotted decimal
(i.e. 1.2.3.4)

#### user.adblocked 
|  |  |
|----|------|
| Required | Yes if the user is being adblocked
| Type | String | 
Indicates if an adblocker is being used or not. Default value is “false”.
If the user is being adblocked, “true” value should be sent

#### user.id 
|  |  |
|----|------|
| Required | Yes Required if the request is sent through a server
| Type | String | 

An opaque, anonymized and unique identifier of the user that is
currently using the application (e.g. a browser cookie or internal app
user id).

#### user.unified-id
|  |  |
|----|------|
| Required | No
| Type | String | 
An opaque, anonymized and unique identifier of the user in the publisher’s eco-system. This identifier should be identical cross application and device (e.g. hashed e-mail, or login)

#### device.id 
|  |  |
|----|------|
| Required | Yes for app integrations, both client and server
| Type | String | 
An opaque, anonymized and unique identifier of the device being
used, to be used for optimization of recommendation cross
applications. (e.g. IDFA for iOS, AdID for Android, or MS advertisingId)

#### view.id 
|  |  |
|----|------|
| Required | Yes if requesting multiple recommendations in separate API requests for the same page view such as in the case of infinite scroll
| Type | String | 

An id of a single page view, which is used by Taboola to aggregate
different requests to the same page view in reporting, as well as to de-
duplicate recommendations between multiple widgets on the same
page view Different requests should have the same view.id if they are displayed
on the same view from the publisher POV.

The view.id is required to be unique only in the context of the same
session, so there is no need to supply a globally unique view id

Example:
```
[http://api.taboola.com/1.2/json/publisher-](http://api.taboola.com/1.2/json/publisher-)
demo/recommendations.get?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&placement.rec-
count=4&placement.organic-
type=video&user.session=init&source.type=video&source.id=214321562187&source.url=http%3A%2F%2Fwww.site.com%2F
videos%2F214321562187.html
```

The application should call the “recommendations.multiple-get” method to generate one or more lists of recommendations, so each list will be displayed on a separate module on the page. Each module on the page has
its own unique placement value. When sending a multiple request, you are asking for one or more chunks of recommendations.

### recommendations.multiple-get
#### app.type 
|  |  |
|----|------|
| Required | yes |
| Type | String | 

The API key that was provided by Taboola for the application

#### app.apikey 

|  |  |
|----|------|
| Required | no |
| Type | String | 

An optional argument specifying the current application name. Not needed if the application name is added to the user agent (either automatically like in iOS, or manually) 

#### placement.name 
|  |  |
|----|------|
| Required | no |
| Type | String | 

A text string, uniquely identifying the placement of a widget using the recommendations response in the application. If provided, this will allow breaking down reporting, and specifically controlling the recommendations behavior for each placement (similar to Google AdSense custom channels). “source.placement” is supported for backward compatibility For example, if the application uses recommendations on both “articles” and blog posts, “source.type” on both pages would need to be “text”, but the “placement” on the former might be “article” and “blog” on the latter. Another example – if the application places two recommendation modules on the video page, one below the player and one to the right, the placement parameter might be “below player” for the first and “right rail” for the second 

#### placement.rec-count 

|  |  |
|----|------|
| Required | no |
| Type | Integer | 

A non-negative integer specifying how many recommendations are requested. The API will not return more recommendations than this, though if there are not enough good quality recommendations to satisfy the request, fewer items might be returned. “rec.count” is supported for backward compatibility

 #### placement.organic-type

|  |  |
|----|------|
| Required | no |
| Type | String | 


Valid values:

| Value | Details |
|----|----|
 | video  | return only video content ( default )
 | text  | return only textual (stories) content
 | photo | return only photo / galleries content
 | mix  | return a mix of several content types. In case a mix is requested, the exact mix is determined by server side configuration. Different configurations can be used for different source.type and placement parameters.

#### lacement.thumbnail.width
#### placement.thumbnail.height

|  |  |
|----|------|
| Required | no |
| Type | Integers | 

The size (in pixels) of the thumbnails returned for recommendations.
Both parameters (height and width) should either appear together or
not appear at all. In case the thumbnail size parameters are specified, the thumbnail
would always preserve its original aspect ratio – it will be scaled to the
required size, centered and cropped if needed. In addition, in case the thumbnail contains a face, we will detect that face by default and ensure it is contained within the generated
thumbnail.  “rec.thumbnail.width” / “rec.thumbnail.height” are supported for backward compatibility

#### placement.visible 

|  |  |
|----|------|
| Required | no |
| Type | Boolean | 

Indicates whether the recommendations are visible right after the
“recommendations.get” request. Default is “true”
In case this argument is set as “false”, a separate
“recommendations.notify-visible” event should be sent when
the recommendations are actually visible.
“rec.visible” is supported for backward compatibility

#### placement.available

|  |  |
|----|------|
| Required | no |
| Type | Boolean | 

Indicates whether  the recommendations were served right after the
“recommendations.get” request. Default is “true”
In case this argument is set as “false”, a separate
“recommendations.notify-available” event should be sent
when the recommendations are served.
**Recommendations are not allowed to be cached more than 30
minutes!**

#### response.callback 

|  |  |
|----|------|
| Required | True if JSONP response is needed |
| Type | String | 

Specifies the name of the callback function to use in the JSONP style
response. “rec.callback” is supported for backward compatibility

#### source.type 
|  |  |
|----|------|
| Required | True |
| Type | String | 

The type of the content the recommendations will be placed next to.
The following values are supported:


| Value | Details |
|----|----|
 | video  | should be passed when the recommendations are placed near a video
 | text  | should be passed when the recommendations areplaced near a textual piece such as an article / story
 | photo  |  should be passed when the recommendations are placed near a photo or gallery
 | home  |  should be passed when the recommendations are placed on the app entry (home) screen
 | section  | should be passed when the recommendations are placed on a screen representing “section front” or “topic”
 | search  | should be passed when the recommendations are placed on a search results page

#### source.id 
|  |  |
|----|------|
| Required | True |
| Type | String | 

The id of the item for which the recommendations should be provided.
Please consult your Taboola account manager regarding which ID
should be provided here for each type of content

### source.url 
|  |  |
|----|------|
| Required | True |
| Type | String | 

A fully qualified (http:// or https://) publicly accessible URL that
contains the content and/or meta data for the current source item (the
piece of content the recommendations are going to be placed next to).
#### User.session 
|  |  |
|----|------|
| Required | True |
| Type | String | 
Should send either the value “init” for the first request in a session or the session value from the response to the last “recommendations.get” request in the session.
User.referrer Recommended String The referrer (HTTP header) from the request that led to the current page.

#### User.agent
|  |  |
|----|------|
| Required | No |
| Type | String | 

is sent through a server
String The user-agent (HTTP header) from the client side request.

####  User.realip Required if the request

|  |  |
|----|------|
| Required | Yes Required if the request is sent through a server|
| Type | String | 

The real IP address of the client side request. Required in case the
request is sent through a server. Should be formatted as dotted decimal
(i.e. 1.2.3.4)

#### user.adblocked 
|  |  |
|----|------|
| Required | Yes if the user is being adblocked
| Type | String | 
Indicates if an adblocker is being used or not. Default value is “false”.
If the user is being adblocked, “true” value should be sent

#### user.id 
|  |  |
|----|------|
| Required | Yes Required if the request is sent through a server
| Type | String | 

An opaque, anonymized and unique identifier of the user that is
currently using the application (e.g. a browser cookie or internal app
user id).

#### user.unified-id
|  |  |
|----|------|
| Required | No
| Type | String | 
An opaque, anonymized and unique identifier of the user in the publisher’s eco-system. This identifier should be identical cross application and device (e.g. hashed e-mail, or login)

#### device.id 
|  |  |
|----|------|
| Required | Yes for app integrations, both client and server
| Type | String | 
An opaque, anonymized and unique identifier of the device being
used, to be used for optimization of recommendation cross
applications. (e.g. IDFA for iOS, AdID for Android, or MS advertisingId)

#### view.id 
|  |  |
|----|------|
| Required | Yes if requesting multiple recommendations in separate API requests for the same page view such as in the case of infinite scroll
| Type | String | 

An id of a single page view, which is used by Taboola to aggregate
different requests to the same page view in reporting, as well as to de-
duplicate recommendations between multiple widgets on the same
page view Different requests should have the same view.id if they are displayed
on the same view from the publisher POV.

The view.id is required to be unique only in the context of the same
session, so there is no need to supply a globally unique view id

Example:
```
http://api.taboola.com/1.2/json/publisher-demo/recommendations.multiple-get?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&placement1.name=Above%20Player&placement 1 .rec-count=4&placement 1 .organic-
type=video&placement1.visible=false&placement1.available=false&placement1.thumbnail.width=200&placement1.thumbnail.height=100&placement2.name=Below%20Player&placement2.rec-count= 6 &placement2.organic-type=mix&placement 2 .visible=false&placement 2 .available=false&placement 2 .thumbnail.width=250&placement1.thumbnail.height=200&user.session=init&source.type=video&source.id=214321562187&source.url=http%3A%2F%2Fwww.site.com%2Fvideos%2F214321562187.html
```

## Recommendations  response

 The response for “recommendations.multiple-get” is a response entity with mapped recommendations chunks to their relevant recommendations lists. Each recommendation chunk gets its own list, as if it was sent separately, but from Taboola’s server side we count it as a single page view and avoid duplications if configured to do so.
 * Session data given in the response entity should be used by all events related to this response entity content
 * Each recommendations list linked to a response id, which should be used by all events related to the recommendations list content

Example (response entity  scheme):
```javascript
{
  "session”: “overall session data”,
  "placement1":{“id": rec1 response id, “list”: [rec1 array of objects]},
  "placement2":{“id": rec2 response id, “list”: [rec2 array of objects]},
  "placement3":{“id": rec3 response id, “list”: [rec3 array of objects]},
...
}
```
Example (detailed with  2 placements):
```javascript
{
  "session": "ksdj394uqpdj329ru3",
  "placement1": {
    "id": "3285432875",
    "ui": "thumbnails-1x1",
    "list": [
      {
        "type": "video",
        "id": "sdkfhg324324",
        "name": "Cool video #1",
        "url": "http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-click?apptype=mobile&app.apikey=1234567&response.id=__3285432875__&response.session=ksdj394uqpdj329ru3&item.id=sdkfhg324324&item.type=video&redir=http://www.google.com/videos/2012/steno12-sr.html",
        "created": "Sat, 26 Mar 2011 03:44:31 GMT",
        "description": "Lorem ipsum dolor sit amet",
        "thumbnail": [
          {
            "url": "http://image.com/image1.png",
            "width": 160,
            "height": 90
          },
          {
            "url": "http://image.com/largeimage1.png",
            "width": 480,
            "height": 270
          }
        ],
        "author": "John Doe",
        "categories": [
          "news",
          "sports"
        ],
        "duration": 180,
        "views": 1999
      },
      {
        "type": "video",
        "origin": "sponsored",
        "id": "$sponsored:325:sdkfhg324325",
        "name": "Sponsored video #2",
        "url": "http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-click?apptype=mobile&app.apikey=1234567&response.id=__a01234567b__&response.session=ksdj394uqpdj329ru3&item.id=$sponsored:325:sdkfhg324325&item.type=video&redir=http://www.google.com/videos/2012/sponsored.html",
        "thumbnail": [
          {
            "url": "http://image.com/image2.png"
          }
        ],
        "branding": "Google"
      }
    ]
  },
  "placement2": {
    "id": "328543287 6 ",
    "list": [
      {
        "type": "photo",
        "origin": "sponsored",
        "id": "$sponsored:325:sdkfhg324 444 ",
        "name": "Sponsored photo #1",
        "url": "http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-click?apptype=mobile&app.apikey=1234567&response.id=__a01234567b__&response.session=ksdj394uqpdj329ru3&item.id=$sponsored:325:sdkfhg324444&item.type=photo&redir=http://www.google.com/photos/2012/sponsored.html",
        "thumbnail": [
          {
            "url": "http://image.com/image2.png"
          }
        ],
        "branding": "Google"
      }
    ]
  }
}
```
The response for “recommendations.get” will be a JSON formatted string that contains the generated response id and a recommendations list. In case an output.callback parameter is specified, the response will be padded with a callback. The same data is mapped to each recommendation placement in the response entity for

 “recommendations.multiple-get”

- **Recommendation  List:**

```
Name Required / Optional Type Description
```
**id** (^) **Required** String Unique Taboola recommendations id.
Should be saved and sent in each notification event connected to the
“recommendations.get” request or per mapped recommendations chunk (recX) when
using “recommendations.multiple-get” request
**session** (^) **Required** String Taboola session data.
The value from the last request in a session should be saved and send in any subsequent
request or event notification
Note that this value is not a fixed session id and can change from request to request – so
it’s imperative to use the session data from the last request in a session
**ui Optional** String UI mode name as defined in Taboola internal mediation table. The UI is returned in case
the Taboola system is configured to override the default UI (due to mediation, full page
personalization or A/B test) for the requested placement. The list of possible UI values
should be agreed beforehand between Taboola and the publisher, and the client should
have a function that renders the relevant UI according to the UI value in the response
**variant** (^) **Optional** String Variant name as defined in Taboola A/B test system. Taboola system is configured to
return variant name in case an A/B test is running on the requested placement. The list of
possible variants values should be agreed beforehand between Taboola and the publisher,
and the client should have a function that renders the relevant UI according to the variant
and UI values in the response
**list Required** Array of
Recommended
Item Objects
An array of recommended item, each is an object with field as specified in the following
table

 The recommendations list is made up of a list of recommended items that may be of multiple types, though for

 the purpose of this specification version only the type “video” will be supported.

```
Comment [TH3]: Added variant as it wasn’t set in the previous
document version
```

- **Recommended Item:**

**Name Required / Optional Type Description
Fields common for all Recommendable Item objects:
type Required** String Type of recommended item. The value of this field is one of:

video (^) video content
text textual (stories) content
photo^ photo / galleries content^
origin Optional String An indication on the origin of the content – whether it is organic (from your own site),
in-network (from other sites within your network) or sponsored (from other content
providers that pay Taboola to distribute their content).
Valid values are:
organic Organic content ( **default** )
sponsored Sponsored content
network (^) From other sites within your network
native_rec^ Native content^
**id** (^) **Required** String Identifier of the recommended item. This id should be sufficient for the application to
know how to play / present the recommendation when clicked
**name Required** String Name / Title of the recommended item
**url Required** String Click URL. To be used when the user clicks on the items image / title / call to action
button
created (^) Optional String Date and time the item was created / published, in RFC 1123 format. For example "Mon,
26 Mar 2011 03:44:31 GMT".
thumbnail Optional Array of
Objects
List of thumbnails associated with the recommendation. Each thumbnail information is
an object with the following fields:
**Name Type Description**
url String The URL for loading the thumbnail
width Integer The width of the image in pixels
height Integer The height of the image in pixels
Note: the width and height fields are optional when a single thumbnail is returned in the
list, but are guaranteed to be supplied with each thumbnail when multiple thumbnails are
returned.
disclosure Optional String Disclosure url, that should be used as Adchoices icon link presented on the relevant item
thumbnail, during mouseover.
description Optional String Description for the recommended item
author (^) Optional String Author/Uploader of the recommended item
categories Optional Array of
Strings
An array of category tags for the recommended item
**Additional Fields for a Recommended Item of type = video:**
duration Optional Integer Duration of the video in seconds
views Optional Integer Number of views for the video
rating Optional Integer Rating for the video in a scale of 0- 10
**Additional Fields for a Network/Sponsored Recommended (origin=”sponsored” or origin=”network”):**
branding Required when origin =
”sponsored”/”network”
String Branding text for the network/sponsored item.
Sponsored recommendations must have this text displayed in a visible location within the
recommendation (such as near or below the title)
**Comment [LG4]:** Will we want to add here additional types such
as “product” and “app”?
**Comment [TH5R4]:** App and Product aren’t defined as types by
the Media. Do you want me to talk with Eyal D about this matter?
(App is defined as Advertisement type)
**Comment [LG6]:** What about native?
**Comment [TH7R6]:** Addded


**Name Required / Optional Type Description**
pixels Required when origin =
“sponsored”/“network”
and the Advertiser set
pixels in Taboola
platform

```
Array of
Pixel
objects
```
```
The pixel array should return if the advertiser set tracking pixel(s) for the relevant item.
Each pixel object has the following fields:
Name Type Description
url String The pixel url to be fired on the defined event
event Integer The event that triggers the pixel fire. Event values are:
available, visible and click.
```
```
Those tracking pixels should be fired on either “available” (when the widget is rendered),
“visible” (when the widget is made visible), or “click” (when the item is clicked). It is
possible to have more than one pixel for the same event
```
- **Example:**

{
"id":"3285432875",
"session":"ksdj394uqpdj329ru3",
"list": [ {
"type":"video",
"id":"sdkfhg324324",
"name":"Cool video #1",
"url”:"http:// api.taboola.com/1.2/json/publisher-demo/recommendations.notify-
click?apptype=mobile&app.apikey=1234567&response.id=__3285432875__&response.session=ksdj394uqpdj329ru3&item.i
d=sdkfhg324324&item.type=video&redir=http://www.google.com/videos/2012/steno12-sr.html",
"created":"Sat, 26 Mar 2011 03:44:31 GMT",
"description":"Lorem ipsum dolor sit amet",
"thumbnail": [ { "url":"http://image.com/image1.png", "width":160, "height":90 },
{ "url":"http://image.com/largeimage1.png", "width": 480 , "height": 270 } ],
"author":"John Doe",
"categories":["news","sports"],
"duration":180,
"views":
}, {
"type":"video",
"origin":"sponsored",
"id":"$sponsored:325:sdkfhg324325",
"name":"Sponsored video #2",
"url”:"http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-
click?apptype=mobile&app.apikey=1234567&response.id=__a01234567b__&response.session=ksdj394uqpdj329ru3&item.i
d=$sponsored:325:sdkfhg324325&item.type=video&redir=http://www.google.com/videos/2012/sponsored.html",
"thumbnail": [ { "url":"http://image.com/image2.png" } ],
"disclosure":"//adchoices-link-per-advertiser.html",
"pixels": [ { "url":"...","event":"visible" }, { "url":"...","event":"click" } ],
"branding":"Google"
} ]
}


## 3 .  Recommendations Events  API

 In certain use cases, Taboola can’t track the interactions of the user with the recommendations and need the

 application to send certain events. These include the following use cases and corresponding events:

 1. When  selected  recommendations are displayed without going through the item  URL (for  example – when  

 playing  a selected  video based on  its id) – the application is  required  to  notify  Taboola of clicks by  sending a 

 “notify-click” event

 2. When  recommendations are retrieved but not displayed immediately (for  example – when  requesting  

 recommendations  at  the beginning of  a video play  but displaying  them  only  when  the video completed playing)  

- the application should  invoke  the recommendations.get request with  placement.available=false and 

 placement.visible=false  / recommendations.multiple-get  request with  placementX.available=false and  

 placementX.visible=false arguments,  and then  should  notify  with  “notify-availble” event when  the 

 recommendations  are displayed and “notify-visible”  event when  the recommendations are actually  visible.

 Note that  “notify-visible”  event can also  be  used  in  cases where the recommendations are displayed below 

 the  fold, in  which case  it  is  recommended to  send  a “notify-visible”  event only  when  the recommendations 

 surface  above the fold.

### 3.1.  Click Notification

 When the user selects a recommendation, and the recommended item is displayed directly by the app (without

 going through the URL), the application should send the "notify-click" event, passing the session from the

 response to the last request, and the id of the actual response that corresponds to the selected recommendation,

 along with the id and type of the selected item

- **Method  Name: "recommendations.notify-click"**
- **Request Arguments:**

```
Name Required /
Optional
```
```
Type Description
```
app.type Required String Type of application using the API.
Valid values: same as the one that was sent in "recommendations.multiple-get"
call /"recommendations.get" call

app.apikey (^) Required String The API key that was provided by Taboola for the application
response.id Required String The “id“ field that was received in the response to the corresponding
"recommendations.multiple-get" call /"recommendations.get" call
response.session (^) Required String The “session“ field that was received in the response to the last
"recommendations.multiple-get" request / “recommendations.get”
request
item.type Required String The type of the selected item, as was received in the response to the
"recommendations.multiple-get" call / "recommendations.get" call
item.id Required String The id of the selected item, as was received in the response to the
"recommendations.multiple-get" call / "recommendations.get" call


- **Example:**

[http://api.taboola.com/1.](http://api.taboola.com/1.) 2 /json/publisher-demo/recommendations.notify-
click?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&response.session=idfh2438u20rf29u9&
response.id=2345112123&item.type=video&item.id=

### 3.2.  Availability  Notification

 When the recommendation module is not displayed at the time the recommendation request, the application is

 advised to send a “placement.available=false” / “placementX.available=false” argument in the request, and then

 later on to send a “notify-available” event when the recommendation module is actually displayed, passing the

 session from the response to the last request, and the id of the actual response that corresponds to the visible

 recommendations.

 * Due to Taboola backend settings a response shouldn’t be cached more than 30 minutes

- **Method  Name: "recommendations.notify-available"**
- **Request Arguments:**

```
Name Required /
Optional
```
```
Type Description
```
app.type
Required String Type of application using the API.
Valid values: same as the one that was sent in "recommendations.multiple-get" call
/ "recommendations.get" call
app.apikey Required String The API key that was provided by Taboola for the application

response.id (^) Required String The “id“ field that was received in the response to the corresponding
"recommendations.multiple-get" call / "recommendations.get" call
response.session Required String The “session“ field that was received in the response to the last
“recommendations.multiple-get” request / “recommendations.get” request

- **Example:**

[http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-](http://api.taboola.com/1.2/json/publisher-demo/recommendations.notify-)
available?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&response.id=

### 3. 3 .  Visibility Notification

 When the recommendation module is not visible to the viewer at the time the recommendation request, the

 application is advised to send a “placement.visible=false” / “placementX.visible=false” argument in the request,

 and then later on to send a “notify-visible” event when the recommendation module is actually visible to the

 viewer, passing the session from the response to the last request, and the id of the actual response that

 corresponds to the visible recommendations. This event should be sent after available event was sent, unless

 “placement.available” / “placementX.available” was send with “true”

 * Module is considered visible if the viewer has the center of the module appearing for 1 second in the viewport

- **Method  Name: "recommendations.notify-visible"**
- **Request Arguments:**

```
Name Required /
Optional
```
```
Type Description
```
app.type Required String Type of application using the API.


Valid values: same as the one that was sent in "recommendations.multiple-get" call
/ "recommendations.get" call
app.apikey Required String The API key that was provided by Taboola for the application
response.id Required String The “id“ field that was received in the response to the corresponding
"recommendations.multiple-get" call /"recommendations.get" call
response.session Required String The “session“ field that was received in the response to the last
"recommendations.multiple-get" request / “recommendations.get” request

- **Example:**

[http://api.taboola.com/1.](http://api.taboola.com/1.) 2 /json/publisher-demo/recommendations.notify-
visible?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd0&response.id=


## 4 .  User  Data API

 The user data has great value to the Taboola eco system. In server-to-server integration Taboola REST API

 request won’t have the same data as if it is client-to-server request. Some of this data is relevant to personalize

 Taboola recommendations in order to optimize performance, and in order to provide this data for server to

 server integration, we recommend adding a user id sync API call

### 4. 1 .  User  sync event

 In a server-to-server integration, Taboola can’t get the Taboola user-id from the browser cookie. In case the

 client side has access to the main browser, the user sync event can be used to get the Taboola user-id and then

 use it when asking for recommendations.

 The Taboola user id can be cached on the server side for up to 1 month, after which it should be refreshed.

 The recommended flow:

 1. Page  starts  to  load  ->  check if  a cached  Taboola user  id  value exist and is  less  than  1 month old

 1.1. No  cached  Taboola user  id, or  cached  id  is  too old ->  fire a  user  sync  event from  the client  side, and wait  for 

 its  response

 1.2. Get the user  sync  event response  and extract the Taboola user  id  

 2. Now,  equipped  with  the Taboola user  id  (either from  the cache or  from  the response  to  the user  sync  API)  ->  

 proceed  with  sending the recommendations.get (or multi-get)  request from  the server, populating  the user.id 

 field  with  the relevant  Taboola user id

 3. The Taboola server  will  now be  able  to  utilize knowledge about the user  from  the entire  Taboola network in  

 order  to better personalize the recommendations

- **Method  Name: "user.sync"**
- **Request Arguments:**

```
Name Required /
Optional
```
```
Type Description
```
app.type
Required String Type of application using the API.
Valid values: same as the one that was sent in "recommendations.multiple-get" call
/ "recommendations.get" call

app.apikey (^) Required String The API key that was provided by Taboola for the application

- **Example:**

[http://api.taboola.com/1.2/json/publisher-](http://api.taboola.com/1.2/json/publisher-)
demo/user.sync?app.type=mobile&app.apikey=a8fdc205a9f19cc1c7507a60c4f01b13d11d7fd

### 4.2.  User  sync  response

 The response is the Taboola user id as it set in the browser’s cookie.


- **Example:**

 { "user": { "id": "<value>" } }