API Concepts
Search
Section titled “Search”The client may not always know the identifiers of the desired documents, so the Content Discovery service offers a way to query documents using the search functionality. To perform a search, the client can leverage the query query parameter in the request.
The ‘query’ parameter is required in all search requests and allows for building complex query expressions.
Query Syntax
Section titled “Query Syntax”The syntax for a query is as follows:
- A query consists of one or more clauses.
- A clause can contain an attribute and an expected value, such as
genre: action. This clause will search for documents where thegenreattribute is equal toaction. - A clause can also be a group of clauses linked with conditional operators like ‘AND’ or ‘OR’:
AND: Represents an AND-conditional operator. For example, the clauseactor: John AND director: Peterwill return all documents that match both the conditionsactor: Johnanddirector: Peter.OR: Represents an OR-conditional operator. For example, the clauseactor: John OR director: Peterwill return all documents that match either the conditionactor: Johnordirector: Peter.
- Clauses can be grouped using parentheses ’(’ and ’)’, creating a new clause.
- When searching for multiple values for a given term, the values need to be wrapped in double quotes (”). For example, the query
query=title:"My new title"will search for documents with the title “My new title”. - Clauses can contain a list of values instead of a single value. For example, the clause
genre: (Comedy Drama)will return all documents where the genre is either “Comedy” or “Drama”. - Clauses can also represent a range of values. For example, the clause
team-ids: [10 TO 20]will return all documents where the team ID is between 10 and 20. - Individual clauses in the query may be boosted to increase their relative importance. To boost a term, use the caret symbol (
^) followed by an integer boost factor at the end of the clause. For example,genre:foo OR actor:bar^2will prioritize documents that match the conditionactor:barovergenre:foo. The higher the boost factor, the more relevant the term will be. By default, the boost factor is 1. - Fuzzy searches can be used to match terms that are similar but not necessarily equal to a given term. Use the tilde symbol (
~) to specify a fuzzy search. For example,actor:name~will match documents with actor names that are similar to “name”. - A clause can be negated by prepending the symbol
-in front of the clause. For example,-genre:Comedywill search for all genres except “Comedy”. - It is possible to search for prefix matches for each individual term by appending the symbol
!at the end of the value. For example,genre:dra!will match documents withgenre:dramaandgenre:dramatic. Due to the high query cost in terms of resources involved, Vimond needs to whitelist the set of metadata intended to be used in a prefix query, as well as the minimum and maximum length of the prefix to search for.
📘 Structure your queries to be cacheable
To ensure the cacheability of your queries, it is recommended to sort all query parameters and query clauses alphabetically. If you are using lists inside clauses, sort the values inside the list alphabetically or in ascending order.
If queries become very large, containing several separated sections bundled together, consider splitting them into smaller queries that are more cacheable.
Query Examples
Section titled “Query Examples”# Get all of the assets with genre "action" that were directed by "Derp"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?query=director:Derp AND genre:action'
# Get all the categories which title contains "big bang"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?query=title:big bang'
# Get all of the assets that were produced in 1965 or all of the musicals from "Matteo Luzzi"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?\query=production-date:1965 OR (genre:musical AND producer:Matteo Luzzi)'
# Get all of the assets that were produced in the '60s"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?\query=production-date:[1960 TO 1969]'
# Get all of the musicals that were produced in 1960 or 1965"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?\query=genre:musical AND production-date:(1960 1965)'
#Get all the assets whose title begins with the prefix "Lor" such as "Lord of the rings" and "Lord of war"curl -X GET \'https://{tenant}.content-discovery.cf.{domain}\/api/v1/assets?\query=title:Lor!'Sorting
Section titled “Sorting”Sorting is a feature that allows clients to retrieve the results of a query in the desired order, eliminating the need for additional sorting on the client side. You can sort the results based on one or more metadata fields.
When making a search request, you can include the sort query parameter to specify the sorting criteria. By default, the sorting order is ascending. To sort in descending order, prepend the sorting parameter with a -.
For example:
# Get all movies with genre "action" ordered by imdbScore first, then by year and eventually by languageGET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=genre:action&sort=-imdbScore,year,language
# Returns older movies firstGET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=genre:action&sort=year
# Returns newer movies firstGET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=genre:action&sort=-yearYou can specify multiple sorting parameters separated by commas. The search results will be ordered based on the provided criteria.
Time query
Section titled “Time query”To retrieve assets based on their transmission time, you can use the time query feature. It allows you to filter assets based on a specific time range.
To perform a time-based query, you can include the transmissionTime field in the query parameter. The values for the time range should be in a specific format.
Here are some examples of time-based queries using
# Get all assets that are about to be transmitted sorted by the transmission timeGET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=transmissionTime:[now-15m TO now]&sort=-transmissionTime# Use 'now-15m' for now minus 15 minutes# Use 'now-15h' for now minus 15 hours# Use 'now-15d' for now minus 15 days# Use 'now-1y' for now minus 1 year
GET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=transmissionTime:[now TO now%2B15d]&sort=-transmissionTime# Use 'now%2B15m' (now plus 15 minutes) for now plus 15 minutes# Use 'now%2B15h' (now plus 15 hours) for now plus 15 hours# Use 'now%2B15d' (now plus 15 days) for now plus 15 days# Use 'now%2B1y' (now plus 1 year) for now plus 1 year
# Get all assets that were created before a date in the last 2 years, sorted by the creation timeGET https://{tenant}.content-discovery.cf.{domain}/api/v1/assets?query=createTime:[now-1y TO 2022-04-29T12:02:12Z]&sort=createTimeWhen using the ’+’ symbol in time queries, the requests should be in URL-encoded format.
📘 Impact of the now keyword on caching
By default the caching window is two minutes, therefore the maximum drift on caching will be two minutes.
However that using
nowover an explicit time can present a significant advantage in case of service failure. In that case, the stale cache will be returned and the end user will keep getting content displayed. If you use explicit time, in case of service failure your end user might end up getting 4XX or 5XX response code and possibly no content to display since it has never been cached.
📘 Searching on metadata
By default all metadata are interpreted as Strings. It is possible to type these by contacting the Vimond Support Desk.
Pagination
Section titled “Pagination”To handle search requests that return a large number of documents, the Content Discovery API supports pagination using the page[number] and page[size] query parameters.
page[size]: Indicates the number of results to be returned per page. The default value is 10.page[number]: Indicates the number of initial results to skip. The default value is 1.
For example, if your request returned 15 results and you want to show five results per page, you can make the following requests:
GET /api/v1/assets?query=title:big bang&page[size]=5GET /api/v1/assets?query=title:big bang&page[number]=2&page[size]=5GET /api/v1/assets?query=title:big bang&page[number]=3&page[size]=5The response to the request also includes information about pagination, such as the number of hits, total pages, and page size.
Remember that the page size is limited to 50 documents per page.
Below is an example of a search request:
{ "data": [ { "id": "123", "title": "Asset 1", "timestamp": "2018-02-16T08:53:49Z", "createTime": "2016-08-29T12:49:41Z", "category": { "id": "654", "path": "999 654", "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/654" }, "labeledAsFree": false, "drmProtected": false, "duration": 148.356, "description": "UTC" }, { "id": "456", "title": "Asset 2", "timestamp": "2018-02-16T09:00:46Z", "createTime": "2017-10-11T09:30:00Z", "category": { "id": "654", "path": "999 654", "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/654" }, "labeledAsFree": false, "drmProtected": true, "duration": 0, "description": "Catchup" }, { "id": "654", "title": "Asset 3", "timestamp": "2018-02-16T09:01:17Z", "createTime": "2017-10-11T10:00:00Z", "category": { "id": "6471", "path": "999 6471", "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/6471" }, "labeledAsFree": false, "drmProtected": true, "duration": 0, "assetType": " ", "description": "Catchup" } ], "meta": { "numberOfHits": 32, "totalPages": 11, "pageSize": 3 }, "links": { "self": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=2&page[size]=10", "first": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=1&page[size]=10", "prev": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=1&page[size]=10", "next": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=3&page[size]=10", "last": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=11&page[size]=10" }}In the response structure we can identify three main components:
-
‘data’ : List of result documents
-
‘meta’ : Some metadata about the request itself, such as the number of results or the number of pages
-
‘links’: Request pointers for the same request but on different pages
Metadata and Locales
Section titled “Metadata and Locales”All metadata added to documents such as assets or categories can be available in different locales. By default, metadata is interpreted as strings. However, it is possible to type metadata by contacting the Vimond Support Desk.
When making a request, you can specify the locale for which you want to retrieve metadata by setting the Accept-Language request header. The response will include the metadata defined for the specified locale. Additionally, all metadata defined in the * locale will also be included in the response document.
For example, if you have an asset with the following metadata:
{ "title": "What a good day, where I have nothing to say about my colleagues", "description": "A description defined only in the default metadata"}The same asset also has locale-specific metadata for the “zh-tw” locale:
{ title: "我的同事吃太多義大利麵",}Here we do a request for an asset document with the locale set to Chinese
curl -X GET \ https://{tenant}.content-discovery.cf.{domain}/api/v1/assets/73833 \ -H 'Accept-Language: zh-tw'The response will look like this
{ "data": [ { "id": "73833", "title": "我的同事吃太多義大利麵", "timestamp": "2018-03-05T08:32:58Z", "createTime": "2018-03-05T08:32:45Z", "category": { "id": "27351", "path": "999 654 27351", "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/27351" }, "labeledAsFree": false, "drmProtected": false, "duration": 243.533, "assetType": "clip", "description": "A description defined only in the default metadata" } ]}In this example, the title has been automatically picked from the Chinese metadata, and the rest of the common metadata has been added to the response.
🚧 Accept-Language header
Although the Accept-Language definition has coverage for a list of weighted locales, the current implementation of the content discovery only supports a single locale to be passed in this header.
However it is possible to define rules to forward locales to another. For example all locales starting with “en” could be forwarded to en_US as it is the one defined in the metadata.
Filtering
Section titled “Filtering”Filtering fields in the response
Section titled “Filtering fields in the response”To retrieve only specific fields in the response and avoid returning all metadata, you can use the fields query parameter. Specify the fields you want to retrieve, separated by commas.
For example, if you only want to retrieve the title and duration of each asset, you can make the following request:
curl -X GET \ 'https://{tenant}.content-discovery.cf.{domain}\ /api/v1/assets?fields=title,duration&page[size]=3'The response will only include the requested fields. The document identifier will always be present in the response, even if it is not explicitly requested.
{ "data": [ { "id": "73913", "title": "Asset 1", "duration": 55.682 }, { "id": "73833", "title": "Asset 2", "duration": 243.53300000000002 }, { "id": "528", "title": "Asset 3", "duration": 73.412 } ], "meta": { "numberOfHits": 3646, "totalPages": 1216, "pageSize": 3 }, "links": { "self": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?fields=title,duration&page[size]=3", "first": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?fields=title,duration&page[size]=3", "next": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=1&page[size]=3&fields=title,duration", "last": "https//{tenant}.content-discovery.cf.{domain}/api/v1/assets?page[number]=1216&page[size]=3&fields=title,duration" }}Filtering on Platforms
Section titled “Filtering on Platforms”The Content Discovery API supports filtering assets and categories based on the platform they are published on. You can use the platform query parameter to specify the desired platform.
When the platform parameter is not specified in the request, the service defaults it to web. You can filter documents published on specific platforms by providing the platform value in the request.
For example:
# Retrieve documents published on the web platformGET /api/v1/assets?query=title:big bang&platform=web
# Retrieve documents published on the iOS platformGET /api/v1/assets?query=title:big bang&platform=iosBy specifying the platform, you can filter the search results to include only assets published on the desired platform.
For more information about the search endpoints, See the Search APIs documentation.
Asset versions
Section titled “Asset versions”The Content Discovery API supports asset versioning. When retrieving information about assets with multiple versions, you can specify the version parameter to retrieve data specific to that version.
When fetching a specific asset or performing a search request, specifying the ‘version’ parameter ensures that only assets with the given version (matching the query) are returned.
To fetch a specific version of an asset, include the ‘version’ parameter in the request. For example:
# Retrieve an asset with the 'short' version and only the 'title' and 'duration' fieldsGET https://{{tenant}}.{{content_discovery_url}}/api/v1/assets/173690?version=short&fields=title,durationThe response will contain the requested version-specific data.
{ "data": [ { "id": "173690", "title": "breaking news (short)", "duration": 10.0, "version": { "available": [ "short", "main", "full" ], "type": "short" } } ]}If the version parameter is not specified, the response will include information from the logical parent asset (the default version), unless the version is set explicitly to main.
You can also retrieve basic information about other versions of the asset by using the query parameter includeAllVersions=true. This will include information about all available versions, along with the requested version.
For example:
GET https://{{tenant}}.{{content_discovery_url}}/api/v1/assets/173690?version=full&includeAllVersions=trueThe response will include information about all versions of the asset.
{ "data": [ { "id": "173690", "title": "breaking news", "duration": 60.0, "version": { "available": [ "short", "main", "full" ], "type": "full", "data": { "short": { "title": "breaking news (short)" "duration": 10 }, "main": { "title": "breaking news (main)" "duration": 20 } } } } ]}{ "data": [ { "id": "173690", "title": "breaking news", "duration": 60.0, "version": { "available": [ "short", "main", "full" ], "type": "full", "data": { "short": { "title": "breaking news (short)" "duration": 10 }, "main": { "title": "breaking news (main)" "duration": 20 } } } } ]}Non-default asset fields
Section titled “Non-default asset fields”Some asset information is not included in the default response and must be explicitly requested using the ‘extraFields’ query parameter.
One example of such additional field is ‘markers’, which provides asset marker information. To include the ‘markers’ field in the response, use the extraFields parameter:
| Field | Description |
|---|---|
| markers | Asset marker information for the asset, see the description in Terminology and Concepts |
Example request
curl -X GET \ 'https://{tenant}.content-discovery.cf.{domain}\ /api/v1/assets/173781?extraFields=markersThe response will include the requested additional marker information along with the other asset information.
{ "data": [ { "id": "173781", "timestamp": "2019-09-12T06:22:39Z", "createTime": "2019-03-26T11:31:30Z", "category": { "link": "https://{tenant}.content-discovery.cf.{domain}/api/v1/categories/129025", "id": "129025", "path": "999 129025" }, "labeledAsFree": false, "drmProtected": false, "duration": 43.848396734121124, "assetType": "Trailer", "isLive": false, "transmissionTime": "2019-03-26T08:15:52Z", "relatedAssets": [], "qualities": [], "markers": [ { "title": "An index point", "description": "test", "type": "test type", "startTime": 10.035, "endTime": 10.035, "images": { "defaultUrl": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg", "version": "original", "templates": { "regions": [ "eng", "swe", "nor" ], "locations": [ "thumb", "media", "splash", "main" ], "withRegion": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?region=${REGION}", "withLocation": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?location=${LOCATION}", "complete": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?region=${REGION}&location=${LOCATION}" } } }, { "title": "Range marker", "description": "range", "type": "something", "startTime": 13.751, "endTime": 15.555, "images": { "defaultUrl": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg", "version": "original", "templates": { "regions": [ "eng", "swe", "nor" ], "locations": [ "thumb", "media", "splash", "main" ], "withRegion": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?region=${REGION}", "withLocation": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?location=${LOCATION}", "complete": "https://{image-service}/api/v2/img/static_assets/question-mark.jpg?region=${REGION}&location=${LOCATION}" } } } ], "version": { "available": [ "main" ], "type": "main" }, "description": "Through a series of daring escapades deep within a dark and dangerous criminal underworld, Han Solo meets ...", "parent-asset-id": 173690, "description-short": "Through a series of daring escapades deep within a dark and dangerous criminal underworld, Han Solo meets ...", "title": "Solo: A Star Wars Stoy" } ]}