Finding Videos That Have Changed with the Media API

The find_modified_videos method in the Video Cloud Media API is useful for finding videos that have been created, updated, or deleted since a time you choose. By outputting the returned videos in MRSS format, you can create feeds that highlight your newest content. This method also enables you to retrieve videos that are inactive, unscheduled, or deleted.

The find_modified_videos method

The Media API Reference describes all the parameters used with the find_modified_videos method. This method has the following signature:

find_modified_videos(token:String,
  from_date:Integer, filter:List, 
  page_size:Integer, page_number:Integer, 
  sort_by:SortByType, sort_order:SortOrderType, 
  get_item_count:Boolean, video_fields:Set, 
  custom_fields:Set):ItemCollection

This is a read method, so use the Media API read token for your account.

The from_date property is the change date of the oldest video you want returned. It is expressed as the number of minutes since the UNIX epoch (January 1st, 1970 00:00:00 GMT). Here's a utility that converts human-readable dates to UNIX dates in seconds. (There are many others on the web, including epochconverter.com.) You'll need to divide the result by 60 to get the number of minutes.

Filtering by video state

The optional filter property defines the state of the videos to be returned. Set the filter property to a comma-separated list of the video states you want returned. A given video can have only one of the states PLAYABLE, INACTIVE, or DELETED at a given time. However, a video can have one of those three states and also be UNSCHEDULED. We do not return information about former video states, so if a video was set to INACTIVE and then DELETED, it would be returned only by filitering for DELETED, not for INACTIVE. The video state value is case-insensitive, so PLAYABLE, playable, and PlAyAbLe are identical. The valid values for the filter property are:

value	description
PLAYABLE	Videos that are currently playable. This excludes videos that, at the time of the call, were inactive, deleted, or not within a valid scheduling window. If you do not specify a value for the `filter` property, it defaults to PLAYABLE.
INACTIVE	Videos that have been placed in the inactive state. These videos can be programmed but do not appear in players and are not viewable in players.
DELETED	Videos that are in the deleted state. Video Cloud keeps track of deleted videos indefinitely.
UNSCHEDULED	This status includes both videos that have a scheduling window assigned, but which, at the time of the call, are not within the scheduling window, as well as videos that do not have a scheduling window assigned.

Using more than one filter

If you use more than one filter in a find_modified_videos method call, the method returns videos that satisfy all of the filters and the results returned are as follows:

filters	videos returned
DELETED, INACTIVE	deleted or inactive
DELETED, UNSCHEDULED	only deleted, since deleted videos have no schedules
DELETED, INACTIVE, PLAYABLE	all videos
DELETED, INACTIVE, UNSCHEDULED	only deleted or inactive
DELETED, PLAYABLE, UNSCHEDULED	all videos that are not inactive
PLAYABLE, INACTIVE	playable or inactive
PLAYABLE, DELETED	all videos that are not inactive
PLAYABLE, UNSCHEDULED	all videos that are playable or out of scheduling window
PLAYABLE, INACTIVE, UNSCHEDULED	all videos that are playable, inactive, or out of scheduling window, but not deleted
PLAYABLE, INACTIVE, DELETED, UNSCHEDULED	all videos
UNSCHEDULED, INACTIVE	only inactive videos

find_modified_videos examples

Here are several examples that demonstrate how to use the find_modified_videos method:

Deleted videos
Videos modified since midnight October 1, 2008

All deleted items ever deleted from the account

http://api.brightcove.com/services/library?
    token=J4JaPuaOCKkGsy-yrLR9ApnSX4u25dw4R2ihzeedEZA.
    &command=find_modified_videos&get_item_count=true
    &video_fields=name,lastModifiedDate,startDate
    &from_date=0&filter=DELETED

Setting the from_date to 0 means we want all deleted items to be returned.

Out-of-schedule videos modified since midnight October 1, 2008

http://api.brightcove.com/services/library?
    token=J4JaPuaOCKkGsy-yrLR9ApnSX4u25dw4R2ihzeedEZA.
    &command=find_modified_videos&get_item_count=true
    &video_fields=name,lastModifiedDate,startDate
    &from_date=20380320&filter=UNSCHEDULED

Video Cloud

App Cloud

Resources