Discovery API Reference

version 1.5

http://personalization/v1/

Introduction

Ooyala Discovery APIs can be used by client applications to present consumers with content recommendations.

Note that if you are already using an Ooyala Discovery 1.0 API or Ooyala Player-integrated solution for your consumer app, you must not use these in conjunction with an Ooyala Discovery 1.5 API.

Request Authentication

The Ooyala Discovery REST APIs require that you include the <account_token> parameter in each request, as illustrated in the examples. For more information, see the Ooyala Account Token API.

Filters

Filters may be applied along with any Ooyala Discovery API query to restrict the content to specific labels and other available metadata fields. Apart from metadata filters, a content_type filter can also be used to restrict the content to (say) a TV Series (instead of individual video assets that may represent Episodes or Trailers). Note that content_type filtering is available only when your Ooyala content management system (CMS) has content groups configured for your data model.

For a list of all available asset or content group metadata fields, use your Ooyala CMS' /assets API response as reference. Any asset metadata field in that API response can generally be applied as a filter.

For example, if the /assets API response included the following metadata snippet for an asset:

{ "labels" : {"name" : "spotlight", "id" : "12345"} }

then Ooyala Discovery would convert the nested metadata structure into a flattened form that can be used in API filter queries. So, to restrict content recommendations to those assets that are labeled ‘spotlight’, you would use the following filter:

filters=labels.name==["spotlight"]

A Boolean expression with two or more filters may be applied. For example:

filters=labels.name==["spotlight"] AND genre==["action"] AND rating==["PG-13"] AND content_type==["movie"]

API Response

Ooyala Discovery API responses include a list of assets, as well as asset metadata for each asset. These include title and thumbnail, among others available from your Ooyala CMS. Responses will automatically exclude content not in an active state in the CMS.

Responses include an ooyalaDiscoveryContext opaque string with each asset. This string must be returned with all user events (e.g., PLAY) reported via an Ooyala Analytics SDK or API.

For You API

Get content recommendations for the user based on their cross-platform or device-specific consumption history.

/foryou get

get

The For You API returns a list of content ranked based on the user's consumption history. Use an identity management system-assigned UUID for cross-device recommendations, or the Ooyala-assigned UUID for device-specific recommendations.

Request
Response

Query Parameters

account_token: required (string)
The account token obtained from the Ooyala Account Token API for referencing the correct Ooyala account and consumer's UUID. The consumer's UUID may be an Ooyala-generated Device ID or an identity management system-generated GUID.

Example:
```
account_token=OEF5NjZLdzVqVkNLcWphb1h5UVFrS2Q2MXI1UlM3aXRCUUE2OUVjYSt3WWV6UkF0YzgxM1Q1R3A3OGZpd2NsVTVYWVRHNW1hZ0VxNmhab2RFTFFtY3E4ckIrWmcyMDB2RlR0NUxKUERQSG9UY0JBNzYwRTFRanBhUXJTQ1J0T3M=
```
blacklist: (string)
Optional comma-separated list of asset IDs or Ooyala embed codes to be filtered out from the returned list of recommended videos.
content_type: (string)
Optional. The content type to which the Ooyala Discovery API should restrict recommendations.

Example:
```
content_type=series
```
Example:
```
content_type=episode
```
filters: (string)
One or more metadata filters using the boolean AND and OR operations. OR is represented using a comma (,) and may be used as indicated.

Example:
```
filters=genre==["animation"] AND categories==["series","mini-series"]
```
limit: (integer)
Optional. The API will limit the number of assets in the response to this number or default to 100. If there are fewer assets available for the query than the specified limit (or the default), only that many assets will be returned.

Example:
```
limit=10
```

HTTP status code 200

Responses include the following:

status: "success"
payload:

data: Contains an array of assets. The asset detail or metadata included will vary depending on the Ooyala CMS data model configuration.
asset: Asset attributes from the Ooyala CMS.
ooyalaDiscoveryContext: Opaque string for returning with all user events for the asset.
count: The number of assets in the current response. An integer. The count is bounded above by the limit parameter, as well as by the total number of assets matching the given criteria.
total: The total number of assets matching the given criteria. An integer.

error: The error body.

Here is a sample response with the Backlot CMS:

Body

Type: application/json

Example:

{
    "status": "success",
    "payload": {
        "data": [{
            "ad_set_id": null,
            "duration": 0,
            "name": "Rio 2016 Tennis Final Highlights",
            "stream_urls": {
                "smooth": null,
                "itunes": null,
                "ipad": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "flash": "http://my_url/out/u/rcnvic-on-000-c3007-delpkg2-delogg2-abr1/flash.f4m",
                "iphone": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "source_file": null
            },
            "preview_image_url": null,
            "description": "Highlights from Rio Olympics 2016’s Men’s Tennis Final Match.",
            "is_ad": false,
            "file_size": 0,
            "is_live_stream": true,
            "preview": null,
            "price": null,
            "flight_start_time": null,
            "asset_type": "remote_asset",
            "provider_id": 99401,
            "publishing_rule_id": "737ec9b3341d41f6a2ab1181742fc686",
            "stream_id": 0,
            "reconstituted_source_file_available": false,
            "stream_name": null,
            "embed_code": "dpZXZoMDE6reeex-KFZ9UZ4kRbNEG3Pw",
            "processing_progress": 0,
            "hosted_at": "",
            "id": 53289233,
            "labels": [],
            "promo": null,
            "status": "live",
            "error_text": null,
            "external_id": null,
            "metadata": {},
            "created_at": "2016-01-28T05:42:18Z",
            "original_file_name": null,
            "player_id": "46916939be864f9c915b38e30276cb37",
            "time_restrictions": null,
            "updated_at": "2016-02-17T03:20:29Z",
            "processing_end": null,
            "flight_end_time": null,
            "price_group_id": null,
            "ooyalaDiscoveryContext": "AS53JTomPCE8Ojt3b2R5dzQlPHdvdyEnMDsxPDsyd3l3JCAwJyx3bw4IKA=="
        }],
        "count": 1,
        "total": 20,
        "pagination": null
    },
    "error": null
}

HTTP status code 400

Bad request. Messages will be specific to the problem with the request. For example:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please provide a valid access token with your Ooyala provider ID to access Discovery APIs."
    }
}


{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please specify filters correctly. {0}"
    }
}

HTTP status code 401

The error response follows the JSON format defined. For example, if the account_token is not authorized, the response will be

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 401,
        "msg": "Please contact your Ooyala representative to enable Discovery."
    }
}

HTTP status code 404

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 404,
        "msg": "You have used a query path that is not available: {0}"
    }
}

HTTP status code 500

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 500,
        "msg": "An internal error was encountered, please try again."
    }
}

Get related video recommendations based on a reference video.

/related get

get

The Related API returns a list of content related to a reference video based on a combination of content metadata similarity and engagement relatedness.

Request
Response

Query Parameters

account_token: required (string)
The account token obtained from the Ooyala Account Token API for referencing the correct Ooyala account and consumer's UUID. The consumer's UUID may be an Ooyala-generated Device ID or an identity management system-generated GUID.

Example:
```
account_token=OEF5NjZLdzVqVkNLcWphb1h5UVFrS2Q2MXI1UlM3aXRCUUE2OUVjYSt3WWV6UkF0YzgxM1Q1R3A3OGZpd2NsVTVYWVRHNW1hZ0VxNmhab2RFTFFtY3E4ckIrWmcyMDB2RlR0NUxKUERQSG9UY0JBNzYwRTFRanBhUXJTQ1J0T3M=
```
asset_id: required (string)
The unique embed code identifier corresponding to the reference video in question.

Example:
```
asset_id=dpZXZoMDE6reeex-KFZ9UZ4kRbNEG3Pw
```
blacklist: (string)
Optional comma-separated list of asset IDs or Ooyala embed codes to be filtered out from the returned list of recommended videos.
content_type: (string)
Optional. The content type to which the Ooyala Discovery API should restrict recommendations.

Example:
```
content_type=series
```
Example:
```
content_type=episode
```
filters: (string)
One or more metadata filters using the boolean AND and OR operations. OR is represented using a comma (,) and may be used as indicated.

Example:
```
filters=genre==["animation"] AND categories==["series","mini-series"]
```
limit: (integer)
Optional. The API will limit the number of assets in the response to this number or default to 100. If there are fewer assets available for the query than the specified limit (or the default), only that many assets will be returned.

Example:
```
limit=10
```

HTTP status code 200

Responses include the following:

status: "success"
payload:

data: Contains an array of assets. The asset detail or metadata included will vary depending on the Ooyala CMS data model configuration.
asset: Asset attributes from the Ooyala CMS.
ooyalaDiscoveryContext: Opaque string for returning with all user events for the asset.
count: The number of assets in the current response. An integer. The count is bounded above by the limit parameter, as well as by the total number of assets matching the given criteria.
total: The total number of assets matching the given criteria. An integer.

error: The error body.

Here is a sample response with the Backlot CMS:

Body

Type: application/json

Example:


{
    "status": "success",
    "payload": {
        "data": [{
            "ad_set_id": null,
            "duration": 0,
            "name": "Racing.com Demo - Akamai CDN",
            "stream_urls": {
                "smooth": null,
                "itunes": null,
                "ipad": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "flash": "http://my_url/out/u/rcnvic-on-000-c3007-delpkg2-delogg2-abr1/flash.f4m",
                "iphone": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "source_file": null
            },
            "preview_image_url": null,
            "description": "Content served from Akamai CDN for Victorian viewers",
            "is_ad": false,
            "file_size": 0,
            "is_live_stream": true,
            "preview": null,
            "price": null,
            "flight_start_time": null,
            "asset_type": "remote_asset",
            "provider_id": 99401,
            "publishing_rule_id": "737ec9b3341d41f6a2ab1181742fc686",
            "stream_id": 0,
            "reconstituted_source_file_available": false,
            "stream_name": null,
            "embed_code": "dpZXZoMDE6reeex-KFZ9UZ4kRbNEG3Pw",
            "processing_progress": 0,
            "hosted_at": "",
            "id": 53289233,
            "labels": [],
            "promo": null,
            "status": "live",
            "error_text": null,
            "external_id": null,
            "metadata": {},
            "created_at": "2016-01-28T05:42:18Z",
            "original_file_name": null,
            "player_id": "46916939be864f9c915b38e30276cb37",
            "time_restrictions": null,
            "updated_at": "2016-02-17T03:20:29Z",
            "processing_end": null,
            "flight_end_time": null,
            "price_group_id": null,
            "ooyalaDiscoveryContext": "AS53JTomPCE8Ojt3b2R5dzQlPHdvdyEnMDsxPDsyd3l3JCAwJyx3bw4IKA=="
        }],
        "count": 1,
        "total": 20,
        "pagination": null
    },
    "error": null
}

HTTP status code 400

Bad request. Messages will be specific to the problem with the request. For example:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please provide a valid access token with your Ooyala provider ID to access Discovery APIs."
    }
}


{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please specify filters correctly. {0}"
    }
}

HTTP status code 401

The error response follows the JSON format defined. For example, if the account_token is not authorized, the response will be

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 401,
        "msg": "Please contact your Ooyala representative to enable Discovery."
    }
}

HTTP status code 404

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 404,
        "msg": "You have used a query path that is not available: {0}"
    }
}

HTTP status code 500

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 500,
        "msg": "An internal error was encountered, please try again."
    }
}

Get content recommendations based on what is currently trending.

/trending get

get

GET /personalization/v1/trending?account_token=<account_token>&filters=<filters>&content_type=<content_type>

The Trending API returns a list of content ranked based on growth in the recent past. The content that has seen the most growth in terms of views in the recent past will be ranked first.

Request
Response

Query Parameters

account_token: required (string)

The account token obtained from the Ooyala Account Token API for referencing the correct Ooyala account and consumer's UUID where available.

Example:

account_token=OEF5NjZLdzVqVkNLcWphb1h5UVFrS2Q2MXI1UlM3aXRCUUE2OUVjYSt3WWV6UkF0YzgxM1Q1R3A3OGZpd2NsVTVYWVRHNW1hZ0VxNmhab2RFTFFtY3E4ckIrWmcyMDB2RlR0NUxKUERQSG9UY0JBNzYwRTFRanBhUXJTQ1J0T3M=

blacklist: (string)
Optional comma-separated list of asset IDs or Ooyala embed codes to be filtered out from the returned list of recommended videos.
content_type: (string)
Optional. The content type to which the Ooyala Discovery API should restrict recommendations.

Example:
```
content_type=series
```
Example:
```
content_type=episode
```
filters: (string)
One or more metadata filters using the boolean AND and OR operations. OR is represented using a comma (,) and may be used as indicated.

Example:
```
filters=genre==["animation"] AND categories==["series","mini-series"]
```
limit: (integer)
Optional. The API will limit the number of assets in the response to this number or default to 100. If there are fewer assets available for the query than the specified limit (or the default), only that many assets will be returned.

Example:
```
limit=10
```

HTTP status code 200

Responses include the following:

status: "success"
payload:

data: Contains an array of assets. The asset detail or metadata included will vary depending on the Ooyala CMS data model configuration.
asset: Asset attributes from the Ooyala CMS.
ooyalaDiscoveryContext: Opaque string for returning with all user events for the asset.
count: The number of assets in the current response. An integer. The count is bounded above by the limit parameter, as well as by the total number of assets matching the given criteria.
total: The total number of assets matching the given criteria. An integer.

error: The error body.

Here is a sample response with the Backlot CMS:

Body

Type: application/json

Example:

{
    "status": "success",
    "payload": {
        "data": [{
            "ad_set_id": null,
            "duration": 0,
            "name": "Rio 2016 Tennis Final Highlights",
            "stream_urls": {
                "smooth": null,
                "itunes": null,
                "ipad": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "flash": "http://my_url/out/u/rcnvic-on-000-c3007-delpkg2-delogg2-abr1/flash.f4m",
                "iphone": "http://my_url/out/u/protected/rcnvic-mo-000-c3007-delpkg2-delogg2-abr1/index-root-ipad.m3u8",
                "source_file": null
            },
            "preview_image_url": null,
            "description": "Highlights from Rio Olympics 2016’s Men’s Tennis Final Match.",
            "is_ad": false,
            "file_size": 0,
            "is_live_stream": true,
            "preview": null,
            "price": null,
            "flight_start_time": null,
            "asset_type": "remote_asset",
            "provider_id": 99401,
            "publishing_rule_id": "737ec9b3341d41f6a2ab1181742fc686",
            "stream_id": 0,
            "reconstituted_source_file_available": false,
            "stream_name": null,
            "embed_code": "dpZXZoMDE6reeex-KFZ9UZ4kRbNEG3Pw",
            "processing_progress": 0,
            "hosted_at": "",
            "id": 53289233,
            "labels": [],
            "promo": null,
            "status": "live",
            "error_text": null,
            "external_id": null,
            "metadata": {},
            "created_at": "2016-01-28T05:42:18Z",
            "original_file_name": null,
            "player_id": "46916939be864f9c915b38e30276cb37",
            "time_restrictions": null,
            "updated_at": "2016-02-17T03:20:29Z",
            "processing_end": null,
            "flight_end_time": null,
            "price_group_id": null,
            "ooyalaDiscoveryContext": "AS53JTomPCE8Ojt3b2R5dzQlPHdvdyEnMDsxPDsyd3l3JCAwJyx3bw4IKA=="
        }],
        "count": 1,
        "total": 20,
        "pagination": null
    },
    "error": null
}

HTTP status code 400

Bad request. Messages will be specific to the problem with the request. For example:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please provide a valid access token with your Ooyala provider ID to access Discovery APIs."
    }
}


{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 400,
        "msg": "Please specify filters correctly. {0}"
    }
}

HTTP status code 401

The error response follows the JSON format defined. For example, if the account_token is not authorized, the response will be

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 401,
        "msg": "Please contact your Ooyala representative to enable Discovery."
    }
}

HTTP status code 404

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 404,
        "msg": "You have used a query path that is not available: {0}"
    }
}

HTTP status code 500

The error response follows the JSON format defined:

Body

Type: application/json

Example:

{
    "status": "failed",
    "payload": null,
    "error":
    {
        "code": 500,
        "msg": "An internal error was encountered, please try again."
    }
}

Discovery API Reference

version 1.5

Introduction

Request Authentication

Filters

API Response

For You API

/foryou get

get /foryou

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 404

Body

HTTP status code 500

Body

Related API

/related get

get /related

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 404

Body

HTTP status code 500

Body

Trending API

/trending get

get /trending

Query Parameters

HTTP status code 200

Body

HTTP status code 400

Body

HTTP status code 401

Body

HTTP status code 404

Body

HTTP status code 500

Body