Overview: OTT Syndication API

The OTT Syndication API is a publicly accessible API that allows you to create a data set for universal search for different platforms such as Apple TV and Roku from your Beacon media assets. Creating an data set for universal search allows viewers to find your content when they search for movies or series on a platform like Apple TV, Roku, or Fire TV on a device, even if they have not subscribed to your specific app.

Related documents

Introduction

The Brightcove OTT Syndication API is a publicly accessible API that allows syndications to be created, managed, and used to generate data sets for universal search on various OTT platforms such as Apple TV, Roku, and Fire TV, allowing them to display results from your app in top-level searches for movies, series, and so forth.

Availability

The syndication API is available to all Beacon customers. The OTT platforms have different procedures and requirements for including media in universal search, so you will need to work with the specific OTT platforms you want to use.

API reference / base URL / headers

The OTT Syndication API Reference contains all the details about the available operations, fields, and parameters.

The base URL is:

https://social.api.brightcove.com/v1

All requests must be authenticated via an Authorization header:

Authorization: Bearer {your_access_token}

See the next section on authentication for information on access tokens.

For any request that sends a request body, you must also include a Content-Type: application/json header.

Authentication

Access to the Configuration API requires specification of a bearer token from the Brightcove OAuth service in the request's Authorization header. The various API methods also require one of the following operations (depending upon the method accessed) to be specified for the credentials in question:

  • video-cloud/social/mrss/read
  • video-cloud/social/mrss/write

These operations can be configured via the API Authentication section of the Studio Admin Module:

Social Syndication Permissions
OTT Syndication Permissions

Syndication Resource

The syndication resource is an object that defines how the syndication will be created. Here is a sample request body for creating a syndication resource:

      {
        "name": "Apple TV Movie Catalog",
        "type": "umcCatalogCsv",
        "asset_type_filter": [
        "movie"
        ],
        "filename": "apple_tv_movie_catalog"
        }

The response will add some read-only fields:

{
        "id": "7f594cd3-4853-4174-aff3-203c3e99e9c2",
        "name": "Apple TV Movie Catalog",
        "type": "umcCatalogCsv",
        "asset_type_filter": [
        "movie"
        ],
        "filename": "apple_tv_movie_catalog"
        "locator_prefix": "",
        "fetch_unpublished": false,
        "fetch_episodeless": true,
        "fetch_videos": false,
        "fetch_dynamic_renditions": false,
        "fetch_audio_tracks": false,
        "asset_container_type": "list"
        }
Syndication Resource
Field Type Read-Only Description
id String Yes generated when syndication configuration is created
name String No an internal name for this syndication - required for POST requests
type Enum:
  • umcCatalogCsv
  • umcAvailabilityCsv
  • googleVideoSitemapXml
  • universal
 No The type of feed that will be generated. The universal type allows custom feeds to be generated by an uploaded feed template. Required for POST requests. The type may not be changed after the configuration is created.
asset_type_filter Array No Specifies which OTT asset types to include in the generated feed. If unspecified, all types will be included.

Items Enum:

  • movie
  • series
  • season
  • episode
filename String No The filename that should be used for the generated feed results for this syndication within zip results files. Should be a flat filename (no paths) using valid zip filename characters. Should not be the same as the filenames used for any other syndications that might have results included in the same zipped results. If not specified, a unique filename will be generated.
locator_prefix String No An URL that can be used as the prefix for generated universal link locators. Currently only used by syndications of type umcAvailabilityCsv. Typically points to the root of the catalog website.
publish_results Boolean No Default: false
Whether to write generated feed results to a publicly accessible web location. Generated feed results are always written to a privately stored zip file, but if this property is true the feed results will also be written in unzipped form to a cloud storage location that can be accessed via a public CDN-backed URL. The public URL can be found in the stored job's public_results field.
content_type_header String No For public feeds, content type header that the syndication's feed will be served with. If not specified, a default that is specific to the syndication type will be used.
rights_location_filter Array of strings No Specifies whether assets should be filtered out of the generated feed based upon the set of permitted and denied locations in the asset's rights object(s). If set, rights objects are considered valid if at least one of the locations in the filter set is allowed by the rights object's permitted_locations set and is not excluded by the rights object's denied_locations set. Assets with no valid rights objects are excluded from the generated feed. For assets included in the feed, valid rights objects can be accessed by the feed template via a filtered_rights array field on the asset. Location filter values should be upper-cased ISO-3166 two-letter country codes (for example, "US").
fetch_unpublished Boolean No Default: false
Valid only for universal syndications. Specifies whether unpublished OTT assets should be included in set of assets used to generate the feed.
fetch_episodeless Boolean No Default: true
Valid only for universal syndications. Specifies whether OTT series and season assets that have no descendant episodes should be included in set of assets used to generate the feed.
fetch_videos Boolean No Default: false
Valid only for universal syndications. Specifies whether the CMS videos associated with OTT movie and episode assets should be fetched. If true, the CMS video objects will be available to the feed template in a video field for each applicable asset. Setting to true will result in slower feed generation times, only set if CMS video metadata is actually needed.
fetch_dynamic_renditions Boolean No Default: false
Valid only for universal syndications that have fetch_videos set to true. Specifies whether the dynamic rendition metadata for fetched CMS videos should also be fetched. If true, the dynamic rendition metadata be available to the feed template in a video.dynamic_renditions field for each applicable asset. Setting to true will result in slower feed generation times, only set if CMS dynamic rendition metadata is actually needed.
fetch_audio_tracks Boolean No Default: false
Valid only for universal syndications that have fetch_videos set to true. Specifies whether the audio track metadata for fetched CMS videos should also be fetched. If true, the audio track metadata be available to the feed template in a video.audio_tracks field for each applicable asset. Setting to true will result in slower feed generation times, only set if CMS audio track metadata is actually needed.
filter_on_start_date Boolean No Default: false
Valid only for universal syndications. Specifies whether assets should be filtered out of the generated feed based upon the start_date of the asset's rights object(s). If true, rights objects with start_date values after the current datetime are considered invalid and assets with no valid rights objects are excluded from the generated feed. For assets included in the feed, valid rights objects can be accessed by the feed template via a filtered_rights array field on the asset.
start_date_modifier_hours Integer No Default: 0
Valid only for universal syndications with the filter_on_start_date attribute set to true. Specifies a positive or negative number of hours to adjust a rights object's start_date by when evaluating the rights object's start date validity. Can be used for example to include assets in the feed that are not yet within their rights validity window but will be transitioning into that window within a specified future timespan.
filter_on_end_date Boolean No Default: false
Valid only for universal syndications. Specifies whether assets should be filtered out of the generated feed based upon the end_date of the asset's rights object(s). If true, rights objects with end_date values after the current datetime are considered invalid and assets with no valid rights objects are excluded from the generated feed. For assets included in the feed, valid rights objects can be accessed by the feed template via a filtered_rights array field on the asset.
end_date_modifier_hours Integer No Default: 0
Valid only for universal syndications with the filter_on_end_date attribute set to true. Specifies a positive or negative number of hours to adjust a rights object's end_date by when evaluating the rights object's start date validity. Can be used for example to include assets in the feed that have reached the end of their rights validity window within a specified timespan in the past.
rights_type_filter Array of strings No Items enum:
  • FREE
  • SVOD
  • AVOD
  • BUY
  • RENT

Valid only for universal syndications. Specifies whether assets should be filtered out of the generated feed based upon the type of the asset's rights object(s). If set, rights objects with type values not in the specified filter set are considered invalid and assets with no valid rights objects are excluded from the generated feed. For assets included in the feed, valid rights objects can be accessed by the feed template via a filtered_rights array field on the asset.
rights_device_filter Array of strings No Valid only for universal syndications. Specifies whether assets should be filtered out of the generated feed based upon the device set in the asset's rights object(s). If set, rights objects with no devices in the specified filter set are considered invalid and assets with no valid rights objects are excluded from the generated feed. For assets included in the feed, valid rights objects can be accessed by the feed template via a filtered_rights array field on the asset.
asset_container_type String No Enum:
  • list
  • typemap

Default: list

Valid only for universal syndications. Specifies whether the "assets" object that is accessible from the feed template should be a flat list of all fetched assets or a map of asset submaps keyed by OTT asset type. Each asset submap will contain assets of the specified type keyed by the asset id.

Syndication Operations

See the API Reference for full details of the operations available:

The following actions are supported - details of endpoints, parameters, and request and response fields can be found in the API Reference:

Syndication configurations

These operations manage syndication configurations. The actual syndication files are generated and managed using the OTT stored job requests listed next.

OTT stored jobs

Stored job operations are used to generate OTT syndications from syndication configurations asynchronously (because depending on how much content you want indexed for universal search, the resulting file may be very large and take some time to generate and send back). Stored jobs can be run manually as needed and can also be configured to run automatically at scheduled intervals.

Templates for custom OTT feeds

The operations are for managing custom templates for syndications.

Error messages

If any API requests fails, an error message will be returned. Error responses will look like the following:

[
          {
          "error_code" : "Application error code 1",
          "message" : "Application error message 1"
          }, {
          "error_code" : "Application error code 2",
          "message" : "Application error message 2"
          }
          ]

Universal Template Language

Universal syndications allow catalog data to be merged with a custom template to generate any kind of feed desired. The supported template language is Liquid. Feeds for the default syndication types are generated using the same types of templates, You can see the templates provided as samples to help you build custom templates if you need to.

The sections below identify the syndication, asset, source, and digital master properties you can use, as well as an extension to Liquid added for convenience.

To see all Video Cloud video metadata fields with descriptions, to go the CMS API Video Fields Reference.

Top level properties

Video Cloud account id

  • account_id

Collection of video assets retrieved from the catalog (see below for details)

  • assets

Asset properties

The resources in the assets collection are derived from the video resources returned by the CMS Get Videos API method, and all of the same properties are supported, including but not limited to the following:

  • created_at
  • description
  • duration
  • id
  • images
  • images.thumbnail
  • images.poster
  • long_description
  • name
  • original_filename
  • published_at
  • schedule
  • state
  • tags
  • text_tracks
  • updated_at

Asset resources also support the following properties:

  • sources (collection of sources for the video - see the next section for source properties)
  • digital_master (will be empty if no digital master exists - see below for the digital master properties)
  • best_mp4_source (the highest quality MP4 source - may be empty if there are no MP4 sources. Properties will be the same as items returned in the sources)
  • hls_source (returns the HLS source - will be empty if none exists)
  • best_dynamic_rendition_quality (returns the video quality of the video's dynamic rendition with the largest frame size, if dynamic rendition metadata has been fetched for the video. Allowable values are "SD", "HD", "FHD", and "UHD".)

Source properties

The resources in the sources collection for an asset are derived from the video source resources returned by the CMS Get Video Sources API method. The following properties are supported:

  • app_name
  • asset_id
  • codec
  • container
  • created_at
  • duration
  • encoding_rate
  • height
  • size
  • src
  • stream_name
  • type
  • uploaded_at
  • width

Dynamic rendition properties

The dynamic_renditions resource for an asset is derived from the dynamic renditions returned by the CMS Get Digital Master Info API method. The following properties are supported:

  • rendition_id
  • frame_height
  • frame_width
  • media_type
  • encoding_rate
  • created_at
  • updated_at
  • size
  • duration
  • audio_configuration
  • language
  • variant

Extensions to Liquid

csvEscape filter

The csvEscape filter performs CSV escaping on a string.

xmlEscape filter

The xmlEscape filter performs XML escaping on a string.

jsonEscape filter

The jsonEscape filter performs JSON escaping on a string.

toUTC filter

We have extended our Liquid parser to support a toUTC filter which will parse most standard ISO-8601 datetime string formats and transform them into standard UTC datetime strings. This format is acceptable to Liquid's date filter, which can then be used to reformat the timestamps into datetime strings in any desired format. For example:

          <pubDate>{{asset.published_at | toUTC | date: "%a, %d %b %Y
            %H:%M:%S %Z"}}</pubDate>

This produces an output like the following if asset.published_at has a value of 2019-08-09T13:32:52.031Z:: 

          <pubDate>Fri, 09 Aug 2019 09:32:52
            +0000</pubDate>

toEpoch filter

The Liquid parser we use does not support the "%s" token in date filters for converting dates to Unix epoch timestamps. To address this, a toEpoch custom filter is provided that can be used to convert valid date specifications to the epoch format. The filter returns a numeric data value representing milliseconds since the epoch that is suitable for input to mathematical filters. For example:

          <toEpochMillis>{{"now" | toEpoch }}</toEpochMillis>
            <toEpochSeconds>{{"now" | toEpoch | divided_by : 1000 }}</toEpochSeconds>
            <thirtyDaysAgo>{{'now' | toEpoch | minus:2592000000 | fromEpoch }}</thirtyDaysAgo>

produces an output like the following:

          <toEpochMillis>1580917253024</toEpochMillis>
            <toEpochSeconds>1580917253</toEpochSeconds>
            <thirtyDaysAgo>2020-01-06T15:40:53.055Z</thirtyDaysAgo>

fromEpoch filter

The fromEpoch filter converts numbers representing milliseconds since the epoch to UTC date strings. The filter will also accept a string containing the epoch value digits as an input. The output can be passed to the date filter for reformatting if necessary.

For example:

          
            <fromEpochMillis>{{"now" | toEpoch | fromEpoch }}</fromEpochMillis>
            <thirtyDaysAgoAltFormat>{{1580917253024 | fromEpoch | date:"%Y-%m-%d" }}</thirtyDaysAgo>

produces an output like the following:

          
            <fromEpochMillis>2020-02-05T16:09:37.809Z</fromEpochMillis>
            <thirtyDaysAgoAltFormat>2020-02-05</thirtyDaysAgo>