Brightcove Video Cloud: Media API Reference
The Media API allows you tointeract with your Video Cloud library. The API includes Read and Write modules for both videos and playlists. In addition, this reference describes a number of related objects.
For reference information about the objects returned by or passed into the Media API, see the Media Object Reference. In addition to the usage examples included in this reference, see these more extensive examples that demonstrate how to use the Media API.
The Media Write API is available only for Video Cloud Pro and Enterprise customers. If you are interested in upgrading your Video Cloud account, please contact Brightcove for more information.
Service URL
The general service URL for the Media API is:
For all regions except Japan:
api.brightcove.com/servicesFor users in Japan, the serviceURL is:
api.brightcove.co.jp/servicesImportant note for publishers in Japan
Publishers in Japan must use a different URL to access the Media APIs. In each case, instead of using a URL that begins api.brightcove.com, Japanese publishers must use a URL that begins api.brightcove.co.jp.
Video Read APIs
Video Cloud Media APIs provide read access to the videos in a publisher's media library using HTTP calls.Read API calls are made as GET requests to api.brightcove.com/services/library. Arguments are appended as URL params. For example:
api.brightcove.com/services/library?command=search_videos&token=WDGO_XdKqXUpy8fzD41MKA8kAhQRAmdux8cu8LNhRzAywCnuBpgV_A..Methods
search_videos(token:String, all:List, any:List, none:List, sort_by:List, exact:Boolean, page_size:Integer, page_number:Integer, get_item_count:Boolean, video_fields:List, custom_fields:List, media_delivery:Enum, output:Enum):ItemCollection
Searches videos according to the criteria provided by the user.The criteria are constructed using field/value pairs specified in the command. Consider using the search_videos method for video searches rather than using the other find_video read methods. The search_videos method offers more flexible search andsorting options than the find_video methods, and is especially more flexible than the find_videos_by_text and find_videos_by_tags methods. Forspecifications of the search_videos method, see: Searching for Videos with the Media API.
Arguments
| name | type | description |
|---|---|---|
| token | String | The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot). |
| all (optional) | Specifies the field:value pairs for search criteria that MUST be present in the index in order to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to bedisplayName, shortDescription, and longDescription. |
|
| any (optional) | Specifies the field:value pairs for search criteria AT LEAST ONE of which must be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription. |
|
| none(optional) | Specifies the field:value pairs for search criteria that MUST NOT be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription. |
|
| sort_by (optional) | Specifies the field tosort by, and the direction to sort in. This is specified as: sortFieldName:direction If the direction is not provided, it is assumed to be inascending order Specify the direction as ASC for ascending or DESC fordescending. You can sort by the following fields: DISPLAY_NAME, REFERENCE_ID, PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, START_DATE, PLAYS_TRAILING_WEEK, PLAYS_TOTAL. Example: sort_by=PUBLISH_DATE:DESC |
|
| exact (optional) | Boolean | If true, disables fuzzy search and requires an exact match of search terms. A fuzzy search does not require an exact match of the indexed terms, but willreturn a hit for terms that areclosely related based on language-specific criteria. The fuzzy search is available onlyif your account is based in the United States. |
| page_size (optional) | Integer | Number of itemsreturned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you donot set this argument, or if you set it to aninteger > 100, your results willcome back as if you had set page_size=100. |
| page_number (optional) | Integer | Thezero-indexed number of thepage to return. |
| get_item_count (optional) | Boolean | If true, also return how many total results there are; Note that if you omit this argument or set it to false, the returned value will be -1. |
| video_fields (optional) | EnumSet | A comma-separated list of the fieldsyou wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText,tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. Note: in order to return the iOSRenditions or captioning you must specify those field explicitly - they are not included in the default fields. |
| custom_fields (optional) | Set | A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter. |
| media_delivery (optional) | Enum | This is aMediaDeliveryTypeEnum with a value of http, http_iosor default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, iOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP,rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL ofthe master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming. |
| output | Enum | The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and CreatingFeeds for TubeMogul OneLoad with the Media API for code examples. |
Returns
| type | description |
|---|---|
| ItemCollection | A collection of videos, ordered as specified by the sort_by argument. If no sort_by argument is supplied, ordered by relevance. |
Usage
Return videos that include the word "gibbous" in the display name. The collection returned includes the names and short descriptions of the first 3 videos, ordered by modified date:
api.brightcove.com/services/library?command=search_videos&all=display_name:gibbous&video_fields=name,shortDescription&page_size=3&get_item_count=true&sort_by=MODIFIED_DATE:DESC&token=[token]
Examples
For specifications of the search_videos method, see:
- Searching for Videos with the Media API.
find_all_videos(token:String, page_size:Integer, page_number:Integer, sort_by:SortByType, sort_order:SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set,media_delivery:Enum, output:Enum):ItemCollection
Find all videos in the Video Cloudmedia library for this account. Thismethod has the limitation of returning only videos available for play, and does not include videos marked as inactive, currently in the upload process, or outside the scheduled play time. See Searching for Unavailable Videos with the Media API for information about solutions to these limitations.
Arguments
| name | type | description |
|---|---|---|
| token | String | The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot). |
| page_size (optional) | Integer | Numberof items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100. |
| page_number (optional) | Integer | The zero-indexed number of the page to return. |
| sort_by (optional) | SortByType | The field by which to sort the results. A SortByType: One of PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, PLAYS_TOTAL, PLAYS_TRAILING_WEEK. |
| sort_order (optional) | SortOrderType | How to order the results: ascending (ASC) or descending (DESC). |
| get_item_count (optional) | Boolean | If true, also return how manytotal results there are; Note that if you omit this argument or set it tofalse, the returned value will be -1. |
| fields (optional) (deprecated) |
Set | Note that this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. |
| video_fields (optional) | EnumSet | A comma-separated list of the fields you wishto have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. Note: in order to return the iOSRenditions or captioning you must specify those field explicitly - they are not included in the default fields. |
| custom_fields (optional) | Set | A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter. |
| media_delivery (optional) | Enum | This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, iOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming. |
| output | Enum | The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples. |
Returns
| type | description |
|---|---|
| ItemCollection | A collection of videos matching the specified search criteria. |
Usage
Get all videos sorted by most popular:
api.brightcove.com/services/library?command=find_all_videos&sort_by=plays_total&sort_order=DESC&token=[token]
Get the names and IDs of recently published videos:
api.brightcove.com/services/library?command=find_all_videos&sort_by=publish_date&video_fields=name,id&token=[token]
Get the 5 most popular videos from the last 7 days (starting yesterday):
api.brightcove.com/services/library?command=find_all_videos&sort_by=plays_trailing_week&page_size=5&sort_order=DESC&token=[token]
Examples
For more examples of the find_all_videos method:
- See a basic example of how to find all videos for an account.
- Look at
find_all_videosexample code and run the code. - Get all videos from an account using this method with ActionScript 2 and ActionScript 3.
- See how to make a basic Media API request from Flex in ActionScript 3 that returns all videos for an account.
- Generate a video sitemap using the
find_all_videosmethod in the Media API. - Generate a top videos sidebar using this method.
- See how to get all videos for an account by accessing the Media API from .NET.
- Generate an RSS feed of your videos using the
find_all_videosmethod.
find_video_by_id(token:String, video_id:long, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum):Video
Finds a single video with the specified ID. See Accessing Video Content with the Media API for various examples of the find_video_by_id method.
Arguments
| name | type | description |
|---|---|---|
| token | String | The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot). |
| video_id | long | The ID of the video you would like to retrieve. |
| fields (optional) (deprecated) |
Set | Notethat this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If youomit this parameter, the method returns the following fields of the Videos: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek.If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. |
| video_fields (optional) | EnumSet | A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. Note: in order to return the iOSRenditions or captioning you must specify those field explicitly - they are not included in the default fields. |
| custom_fields (optional) | Set | A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter. |
| media_delivery (optional) | Enum | This is a MediaDeliveryTypeEnum with a valueof http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, iOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming. |
| output | Enum | The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argumentwith the read methods to specify theformat of the output. Valid values of the output argument are: json (the default), mrss(RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples. |
Returns
| type | description |
|---|---|
| Video | The Video you requested, with the specified fields populated, or null, if there is no video with that ID. |
Usage
Get the video with the specified ID:
api.brightcove.com/services/library?command=find_video_by_id&video_id=123&token=[token]
Get the long description of the video with its ID:
api.brightcove.com/services/library?command=find_video_by_id&video_id=123&video_fields=longDescription&token=[token]
Examples
For more examples of the find_video_by_id method:
- See Accessing Video Content with the Media API for various examples of the
find_video_by_idmethod. - Retrieve a video title for your twitter post using the
find_video_by_idmethod. - Access the Media API from .NET using the
find_video_by_idmethod. - Display the amount of video views using the
find_video_by_idmethod.
find_related_videos(token:String, video_id:Long, reference_id:String, page_size:Integer, page_number:Integer, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum):ItemCollection
Finds videos related to the given video. Combines the name and short description of the given video and searches for any partial matches in the name, short description, long description, tags, and custom fields of all videos in the Video Cloud media libraryfor this account. More precise ways of finding related videos include tagging your videos by subjectand using the find_videos_by_tags method to find videos that share the same tags: or creating a playlist that includes videos that you know are related. Consider using the search_videos method, which offers more flexible search and sorting options.
Arguments
| name | type | description |
|---|---|---|
| token | String | The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot). |
| video_id (optional) | Long | The ID of the video we'd like related videos for. |
| reference_id (optional) | String | The publisher-assigned reference ID of the video we'd like related videos for. |
| page_size (optional) | Integer | Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 200; if you do not set this argument, or if youset it to an integer > 200, your results will come back as if you had set page_size=200. |
| page_number (optional) | Integer | The zero-indexed number of the page to return. |
| get_item_count (optional) | Boolean | If true, also return how many total results there are; Note that if you omit this argument or set it to false, the returned value will be -1. |
| fields (optional) (deprecated) |
Set | Note that this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. |
| video_fields (optional) | EnumSet | A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video: id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, renditions, iOSRenditions, FLVFullLength, videoFullLength. Note: in order to return the iOSRenditions or captioning you must specify those field explicitly - they are not included in the default fields. |
| custom_fields (optional) | Set | A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter. |
| media_delivery (optional) | Enum | This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, iOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming. |
| output | Enum | The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the outputargument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples. |
Returns
| type | description |
|---|---|
| ItemCollection | A collection of videos, ordered by relevance to the provided video. More related videos areranked higher. If no videos match, the call returns a page of videos ordered by the date they were added to your account, so you will never get an empty result set. |
Usage
Show total number of related videos to video of given ID and display first 3
api.brightcove.com/services/library?command=find_related_videos&video_id=123&page_size=3&get_item_count=true&token=[token]
Get the names of related videos 6-10 (page 2)
api.brightcove.com/services/library?command=find_related_videos&video_id=123&page_size=5&page_number=1&video_fields=name&token=[token]