PROFILE BASED SERVICES

PROFILE BASED SERVICES (2.0.0)

Download OpenAPI specification:Download

Personalized recommendations based on the user's history.

Authentication

APIKeyQueryParam

Security Scheme Type API Key
Query parameter name: apikey

TASTE PROFILE

Weighted and categorized keywords reflecting topics of potential interest for every individual user.

USER SEMANTIC FINGERPRINT

Based on the user's history of interactions with content, the USF is a reflection of the user's favorite topics. Weighted keywords display the user's preferences providing full information on every user's taste.

Authorizations:
path Parameters
user
required
string

Provide the user Id. Example: John - The user id must be provided in UTF-8 standard

Responses

Response samples

Content type
application/json
{
  • "userId": "{UserId}",
  • "keywords":
    [
    ]
}

RECOMMENDED FOR YOU

Real-time and time-based personalized suggestions based on the user's history of interactions.

PROFILE BASED RECOMMENDATION

Display profile-based suggestions presented in a Top N list mode in relevance order. Recommendations are calculated from the user's history of interactions.

Authorizations:
path Parameters
user
required
string

Provide the user Id. Example: John - The user id must be provided in UTF-8 standard

universes
required
Array of strings
Items Enum: "vod" "now" "today" "tonight" "later_tonight" "week" "catchup"

This parameter defines the content universe in which we want to target content recommendations. If you want to call several universes, you have to separate each of them by a comma (,). "Available universes are:" "vod" "catchup" "For tv recommendations one of the following values should be chosen:" "'now', 'today', 'tonight', 'later_tonight' or 'week'"

query Parameters
device
string

Define the platform on which the interactions occurred. This can be helpful to identify discrepancies in usage between platforms like TV, tablet, web, mobile apps.

details
boolean

You can choose to display your meta-data in order to save precious response time. By default this parameter is marked "false", details are not automatically shown. To show details, you have to ask for "true".

skip
integer

You can use this parameter to skip the first results that would be displayed. For example: skip=5 means not showing the first 5 results. Default value=0

limit
integer

Number of results requested (max.100). The default value=10

displaysize
boolean

You can choose to display the total number of results by using "true". The default value= false

sections
string

If you want to restrict the recommendations to a specific section, you can pass the section code as a value to this parameter.

language
string
Enum: "br" "de" "en" "fr" "id" "ms" "ph" "pt" "es" "th"

Language in which the metadata is displayed: *en - english (default) *fr - french *de - german *br - brazilian portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

genres
string

Filter the results according to one or several genres.

catalogs
string

Define your choice of catalog names, in case you have multiple catalogs, on which recommendations are applied, separated by a comma (,).

tabs
string

If your platform's interface is divided into separate sections or tabs for specific content 'groups', you can filter the recommendation for each section with this 'tab' parameter. In order to use this parameter, you must provide information about these specific content sections on your platform to Spideo beforehand and separate each tab by a comma (,).

territories
string

If your platform is available in multiple countries and/or territories, this parameter allows to filter the recommendation results based on these territories. In order to use this parameter you must provide Spideo with the territory rights for each piece of content, within the catalog import process, and indicate for each content item to which territory it belongs.

distributions
integer

"If your platform is available with several distributions business models, this parameter allows to filter the recommendation results based on these distributions. In order to use this parameter you must provide Spideo with the distributions rights for each piece of content, within the catalog import process, and indicate for each content item to which distribution it belongs.Example:TVOD, SVOD, AVOD

offers
integer

"This parameter allows you to filter recommendations results to only provide suggestions on programs available in the user's offers subscribtions. In order to use this parameter you must provide Spideo with the offers rights for each channel, catchup store or VOD catalog.

platform
integer

This parameter allows you to filter the recommendations results on the platforms on which the content are available. In order to use this parameter you must provide Spideo with the platform rights for each piece of content, within the catalog import process, and indicate for each content item to which pltaform it belongs. Example of values that can be configured:stb, ios, android.

infrastructure
integer

"This parameter allows you to filter the recommendations results on the infrastructures on which the content are available. In order to use this parameter you must provide Spideo with the infrastructure rights for each piece of content, within the catalog import process, and indicate for each content item to which infrastructure it belongs. Example of values that can be configured: FTTH, FTTB, ADSL.

operator
integer

"This parameter allows you to filter the recommendations results on the operators on which the content are available. In order to use this parameter you must provide Spideo with the operator rights for each channel, catchup store or VOD catalog.

lineups
string

This parameter allows you to filter the recommendations results on a group of TV channels defined under a lineup id.

channel
string

When the Business Rules Network Restrictions is activated recommendations can be filtered on group of channels. This parameter needs to be added to the recommendation calls to identify for each channel on which group it belongs. When a channel id is entered with this parameter, recommendations will only be provided on the channels linked to the same media group. List of channels by id, separated by a comma (,)Screen reader support enabled.

channels
string

This parameter allows you to filter the recommendations results to only provide results on the channels listed in this parameter. List of channels by id, separated by a comma (,)

recency
integer

"If you want to restrict recommendation only to recent content you can use this parameter. As a value pass the number of months a content item can be recommended after having been added to the catalog. It can for example be based on publication dates. For instance: recency=5 means not showing content that has a publication date >5 months. The default value=0"

Responses

Response samples

Content type
application/json
{
  • "user": "{UserId}",
  • "language": "en",
  • "recordsAllowed": true,
  • "recommendation":
    {
    }
}

SEMANTIC PERSONALIZATION

Personalized suggestions explained by thematic lists corresponding to clusters of keywords relevant to users.

CATEGORIZED RECOMMENDATIONS

Display thematically organized playlists of profile-based suggestions. Recommended content items are presented in groups of categories made up of combinations of two keywords corresponding to every user's tastes. Natural language based explanations help people engage with content in a more intuitive discovery experience.

Authorizations:
path Parameters
user
required
string

Provide the user Id. Example: John - The user id must be provided in UTF-8 standard

universes
required
Array of strings
Items Enum: "vod" "now" "today" "tonight" "later_tonight" "week" "catchup"

This parameter defines the content universe in which we want to target content recommendations. If you want to call several universes, you have to separate each of them by a comma (,). "Available universes are:" "vod" "catchup" "For tv recommendations one of the following values should be chosen:" "'now', 'today', 'tonight', 'later_tonight' or 'week'"

query Parameters
device
string

Define the platform on which the interactions occurred. This can be helpful to identify discrepancies in usage between platforms like TV, tablet, web, mobile apps.

details
boolean

You can choose to display your meta-data in order to save precious response time. By default this parameter is marked "false", details are not automatically shown. To show details, you have to ask for "true".

skip
integer

You can use this parameter to skip the first results that would be displayed. For example: skip=5 means not showing the first 5 results. Default value=0

limit
integer

Number of results requested (max.100). The default value=10

displaysize
boolean

You can choose to display the total number of results by using "true". The default value= false

sections
string

If you want to restrict the recommendations to a specific section, you can pass the section code as a value to this parameter.

language
string
Enum: "br" "de" "en" "fr" "id" "ms" "ph" "pt" "es" "th"

Language in which the metadata is displayed: *en - english (default) *fr - french *de - german *br - brazilian portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

catalogs
string

Define your choice of catalog names, in case you have multiple catalogs, on which recommendations are applied, separated by a comma (,).

tabs
string

If your platform's interface is divided into separate sections or tabs for specific content 'groups', you can filter the recommendation for each section with this 'tab' parameter. In order to use this parameter, you must provide information about these specific content sections on your platform to Spideo beforehand and separate each tab by a comma (,).

territories
string

If your platform is available in multiple countries and/or territories, this parameter allows to filter the recommendation results based on these territories. In order to use this parameter you must provide Spideo with the territory rights for each piece of content, within the catalog import process, and indicate for each content item to which territory it belongs.

distributions
integer

"If your platform is available with several distributions business models, this parameter allows to filter the recommendation results based on these distributions. In order to use this parameter you must provide Spideo with the distributions rights for each piece of content, within the catalog import process, and indicate for each content item to which distribution it belongs.Example:TVOD, SVOD, AVOD

offers
integer

"This parameter allows you to filter recommendations results to only provide suggestions on programs available in the user's offers subscribtions. In order to use this parameter you must provide Spideo with the offers rights for each channel, catchup store or VOD catalog.

platform
integer

This parameter allows you to filter the recommendations results on the platforms on which the content are available. In order to use this parameter you must provide Spideo with the platform rights for each piece of content, within the catalog import process, and indicate for each content item to which pltaform it belongs. Example of values that can be configured:stb, ios, android.

infrastructure
integer

"This parameter allows you to filter the recommendations results on the infrastructures on which the content are available. In order to use this parameter you must provide Spideo with the infrastructure rights for each piece of content, within the catalog import process, and indicate for each content item to which infrastructure it belongs. Example of values that can be configured: FTTH, FTTB, ADSL.

operator
integer

"This parameter allows you to filter the recommendations results on the operators on which the content are available. In order to use this parameter you must provide Spideo with the operator rights for each channel, catchup store or VOD catalog.

lineups
string

This parameter allows you to filter the recommendations results on a group of TV channels defined under a lineup id.

channel
string

When the Business Rules Network Restrictions is activated recommendations can be filtered on group of channels. This parameter needs to be added to the recommendation calls to identify for each channel on which group it belongs. When a channel id is entered with this parameter, recommendations will only be provided on the channels linked to the same media group. List of channels by id, separated by a comma (,)Screen reader support enabled.

channels
string

This parameter allows you to filter the recommendations results to only provide results on the channels listed in this parameter. List of channels by id, separated by a comma (,)

recency
integer

If you want to restrict recommendation only to recent content you can use this parameter. As a value pass the number of months a content item can be recommended after having been added to the catalog. It can for example be based on publication dates. For instance: recency=5 means not showing content that has a publication date >5 months. The default value=0"

Responses

Response samples

Content type
application/json
{
  • "user": "{UserId}",
  • "recordsAllowed": true,
  • "categories":
    [
    ]
}

TV HABITS

Personalized EPG with a immediate access to the user's favorites programs.

YOUR FAVOURITE TV SHOW

Display the user's favorite TV shows and TV events. TV habits identify the next occurrences of the TV shows that the user watches on a regular basis.

Authorizations:
path Parameters
user
required
string

Provide the user Id. Example: John - The user id must be provided in UTF-8 standard

query Parameters
device
string

Define the platform on which the interactions occurred. This can be helpful to identify discrepancies in usage between platforms like TV, tablet, web, mobile apps.

details
boolean

You can choose to display your meta-data in order to save precious response time. By default this parameter is marked "false", details are not automatically shown. To show details, you have to ask for "true".

skip
integer

You can use this parameter to skip the first results that would be displayed. For example: skip=5 means not showing the first 5 results. Default value=0

limit
integer

Number of results requested (max.100). The default value=10

displaysize
boolean

You can choose to display the total number of results by using "true". The default value= false

language
string
Enum: "br" "de" "en" "fr" "id" "ms" "ph" "pt" "es" "th"

Language in which the metadata is displayed: *en - english (default) *fr - french *de - german *br - brazilian portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

catalogs
string

Define your choice of catalog names, in case you have multiple catalogs, on which recommendations are applied, separated by a comma (,).

tabs
string

If your platform's interface is divided into separate sections or tabs for specific content 'groups', you can filter the recommendation for each section with this 'tab' parameter. In order to use this parameter, you must provide information about these specific content sections on your platform to Spideo beforehand and separate each tab by a comma (,).

territories
string

If your platform is available in multiple countries and/or territories, this parameter allows to filter the recommendation results based on these territories. In order to use this parameter you must provide Spideo with the territory rights for each piece of content, within the catalog import process, and indicate for each content item to which territory it belongs.

distributions
integer

"If your platform is available with several distributions business models, this parameter allows to filter the recommendation results based on these distributions. In order to use this parameter you must provide Spideo with the distributions rights for each piece of content, within the catalog import process, and indicate for each content item to which distribution it belongs.Example:TVOD, SVOD, AVOD

offers
integer

"This parameter allows you to filter recommendations results to only provide suggestions on programs available in the user's offers subscribtions. In order to use this parameter you must provide Spideo with the offers rights for each channel, catchup store or VOD catalog.

platform
integer

This parameter allows you to filter the recommendations results on the platforms on which the content are available. In order to use this parameter you must provide Spideo with the platform rights for each piece of content, within the catalog import process, and indicate for each content item to which pltaform it belongs. Example of values that can be configured:stb, ios, android.

infrastructure
integer

"This parameter allows you to filter the recommendations results on the infrastructures on which the content are available. In order to use this parameter you must provide Spideo with the infrastructure rights for each piece of content, within the catalog import process, and indicate for each content item to which infrastructure it belongs. Example of values that can be configured: FTTH, FTTB, ADSL.

operator
integer

"This parameter allows you to filter the recommendations results on the operators on which the content are available. In order to use this parameter you must provide Spideo with the operator rights for each channel, catchup store or VOD catalog.

lineups
string

This parameter allows you to filter the recommendations results on a group of TV channels defined under a lineup id.

channel
string

When the Business Rules Network Restrictions is activated recommendations can be filtered on group of channels. This parameter needs to be added to the recommendation calls to identify for each channel on which group it belongs. When a channel id is entered with this parameter, recommendations will only be provided on the channels linked to the same media group. List of channels by id, separated by a comma (,)Screen reader support enabled.

channels
string

This parameter allows you to filter the recommendations results to only provide results on the channels listed in this parameter. List of channels by id, separated by a comma (,)

recency
integer

If you want to restrict recommendation only to recent content you can use this parameter. As a value pass the number of months a content item can be recommended after having been added to the catalog. It can for example be based on publication dates. For instance: recency=5 means not showing content that has a publication date >5 months. The default value=0"

sections
string

If you want to restrict the recommendations to a specific section, you can pass the section code as a value to this parameter.

Responses

Response samples

Content type
application/json
{
  • "size": "4",
  • "contents":
    [
    ]
}

STEP BY STEP

Step by step recommendation experience.

NEXT IN LINE RECOMMENDATIONS

The step-by-step feature exists in order to facilitate the implementation of lean back, immersive and personalized streaming experiences. This endpoint will return recommended items one after the other instead of showing a long list of content IDs.

Authorizations:
path Parameters
user
required
string

Provide the user Id. Example: John - The user id must be provided in UTF-8 standard

query Parameters
details
boolean

You can choose to display your meta-data in order to save precious response time. By default this parameter is marked "false", details are not automatically shown. To show details, you have to ask for "true".

language
string
Enum: "br" "de" "en" "fr" "id" "ms" "ph" "pt" "es" "th"

Language in which the metadata is displayed: *en - english (default) *fr - french *de - german *br - brazilian portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

Responses

Response samples

Content type
application/json
{
  • "content": "M9352300000",
  • "wishes":
    [
    ],
  • "themes":
    [
    ],
  • "genres": [ ],
  • "guarantee":
    {
    },
  • "language": "en"
}

GUARANTEES

Guarantee the relevancy of a recommendation.

RECOMMENDATIONS EXPLAINED

The purpose of the Guarantee feature is to explain users why they are being recommended content. The explanation comes in two ways. Every recommended content is (i) compared to another title that previously generated a meaningful interaction, (ii) linked to keywords the both pieces of content, the one previously watched and the one recommended, have in common.

Authorizations:
path Parameters
contentId
required
string

Provide the internal ID or 3rd party metadata provider ID. Example: 603

query Parameters
details
boolean

You can choose to display your meta-data in order to save precious response time. By default this parameter is marked "false", details are not automatically shown. To show details, you have to ask for "true".

language
string
Enum: "br" "de" "en" "fr" "id" "ms" "ph" "pt" "es" "th"

Language in which the metadata is displayed: *en - english (default) *fr - french *de - german *br - brazilian portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

Responses

Response samples

Content type
application/json
{
  • "content": "M722830000",
  • "guarantee":
    {
    },
  • "language": "en"
}