Spideo API DOC

Spideo API DOC (3.0.8)

Download OpenAPI specification:Download

Spideo's API offers a collection of endpoints that will allow you to integrate our services into your applications. The APIs are ready to deliver recommendations for Live TV, VoD, and Catch-up along with time-based features.

Authentication

APIKeyQueryParam

Security Scheme Type API Key
Query parameter name: apikey

CONTENT BASED SERVICES

Provide relevant and self-explained content-to-content recommendations.

CATALOG

Global view of the content titles in catalog

Catalog

Display the list of all on-demand content available in your catalog and eligible for recommendations.

Authorizations:
query Parameters
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. The default value=20

catalogs
string

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

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
{
  • "total": 13758,
  • "contents":
    {
    }
}

AGGREGATED INFO

Aggregated view of the content information for recommendation purposes

Content information

For a given content ID, this endpoint returns: the content title, potential external IDs, related moods ("wishes"), related themes, language information as well as semantic pairs.

Authorizations:
path Parameters
contentid
required
string

Define the content on which you want to perform the request.

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

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

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".

Responses

Response samples

Content type
{
  • "title": "Indiana Jones and the Raiders of the Lost Ark",
  • "content": "M7460750000",
  • "wishes":
    [
    ],
  • "themes":
    [
    ],
  • "genres":
    [
    ],
  • "pairs":
    [
    ],
  • "saga":
    [
    ],
  • "language": "en"
}

CONTENT SEMANTICS

Content moods and themes

Content themes

Display related themes in connection with every content item.

Authorizations:
path Parameters
contentid
required
string

Define the content on which you want to perform the request.

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

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

Responses

Response samples

Content type
{
  • "contentid": "M7460750000",
  • "language": "en",
  • "themes":
    [
    ]
}

Content moods

Display related moods in connection with every content item. All moods are retrieved under the "wishes" category in the API response.

Authorizations:
path Parameters
contentid
required
string

Define the content on which you want to perform the request.

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

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

Responses

Response samples

Content type
{
  • "contentid": "M7460750000",
  • "language": "en",
  • "wishes":
    [
    ]
}

RELATED

Algorithms for the exploration of titles around every piece of content

Similar

Return a list of similar titles according to the content characteristics and semantic data.

Authorizations:
path Parameters
universes
required
Array of strings
Items Enum: "vod" "now" "today" "tonight" "later_tonight" "week"

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'"

contentid
required
string

Define the content on which you want to perform the request.

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) *br - brazilian portuguese *fr - french *de - german *pt - portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

skip
integer

For similar content content recommendations, 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

catalogs
string

Define your choice of catalog names, in case you have multiple catalogs, on which recommendations are applied, 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
integer

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

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.

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

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.

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.

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.

channels
string

This parameter allows you to filter the recommendations results to only provide results on the channels listed in this parameter.

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.

user
integer

Identify the user performing the request with a user Id.

Responses

Response samples

Content type
{
  • "content": "M7460750000",
  • "similar":
    {
    },
  • "language": "en"
}

Thematic pairs

This feature provides recommendations in the form of auto-curated thematically organized playlists. These lists are built using a combination of themes and moods. These lists can be retrieved via this endpoint. It can provide up to five rails of playlists of pairs of keywords (moods + themes) explaining to users why a list of content is recommended based on the previous content-id passed on the API request. .

Authorizations:
path Parameters
contentid
required
string

Define the content on which you want to perform the request.

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) *br - brazilian portuguese *fr - french *de - german *pt - portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

skip
integer

For similar content content recommendations, 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

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.

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.

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.

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.

user
integer

Identify the user performing the request with a user Id.

Responses

Response samples

Content type
{
  • "content": "M7460750000",
  • "pairs":
    [
    ],
  • "language": "en"
}

Saga

If the given content Id refers to a movie that is part of a saga, then the endpoint returns a list of the ids of the other movies in this saga. For instance the Harry Potter movies are part of a saga.

Authorizations:
path Parameters
contentid
required
string

Define the content on which you want to perform the request.

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) *br - brazilian portuguese *fr - french *de - german *pt - portuguese *es - spanish *id - indonesian *ms - malay *ph - filipino *th - thai

skip
integer

For similar content recommendations, 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
string

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

catalogs
string

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

Responses

Response samples

Content type
{
  • "content": "M7460750000",
  • "similar":
    {
    },
  • "language": "en"
}

SECTIONS

Semantics sections available to order recommendations

Semantic sections

This endpoint returns the list of sections available in all languages. Sections are sets of filtering criteria based on Spideo’s semantics. When you call this endpoint, it will show you all filters currently available in the catalog. Example; There could be a catalog arranged by the keywords “for kids”, “family”, “history”, “news” and “culture.” These keywords represent all sections associated with the existing content within the catalog.

Authorizations:
query Parameters
themes
string

List of themes by id, separated by a comma (,)

wishes
string

List of wishes by id, separated by a comma (,)

genres
string

Filter the results according to one or several genres.

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.

formattv
string

List of TV formats, separated by a comma (,). Available formats are;

stars
string

List of cast members by id, separated by a comma (,)

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

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

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

For similar content content recommendations, 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

Responses

Response samples

Content type
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]