JSON API.Methods
open.video.find
Returns videos matching query and options specified. This is the basic library search method.
open.video.find(query, returnFields [,options])
parameters
| query | object | Optional. This is an XML-RPC struct, each field in this object/struct narrows down the set of media that will be returned by this query. If no fields are given, then all viewable media on the site are returned. |
|---|---|---|
| ids | array of integers | Returns media with specified ids |
| tokens | array of tokens | Takes an array of upload tokens returned from getUploadTokens. Returns media which match these tokens. Videos which haven’t had video.create called on them will have an unrated age_restriction, so when using the tokens query you must specify age_restriction=0. |
| owners | array of strings | Returns media made by specified users |
| titles | array of strings | Returns the media with matching titles or partial matches |
| createdAfter | ISO 8601 | Returns media created after this date |
| createdBefore | ISO 8601 | Returns media created before this date |
| createdWithin | integer | Returns media that was created within the specified number of seconds. For example, createdWithin= 60*60*24*30 will give all videos created within the last 30 days |
| publishedAfter | ISO 8601 | Returns media published after this date |
| publishedBefore | ISO 8601 | Returns media published before this date |
| publishedWithin | integer | Returns media that was published within the specified number of seconds. For example, publishedWithin= 60*60*24*30 will give all videos published within the last 30 days |
| modifiedAfter | ISO 8601 | Returns media that has been modified after this date |
| modifiedBefore | ISO 8601 | Returns media that has been modified before this date |
| modifiedWithin | integer | Returns media that was modified within the specified number of seconds. For example, modifiedWithin= 60*60*24*30 will give all videos modified within the last 30 days. |
| keywords | array of strings
- or - array of arrays of strings |
Takes a 2 deep nested list of strings For example: [’funny’, [’german shepard’, ’sheep dog’]] matches videos that have the ‘funny’ keyword and either ‘german shepherd’ or ’sheep dog’ keyword. |
| search | array of (strings or arrays of strings) |
Takes a 2 deep nested list of strings. Works in a similar way to keywords, but in addition will match on owner, description, and title. Outer array uses an AND operator, inner array uses OR. |
| preroll | string |
If true restrict videos to ones where users have opted-in to pre-roll advertising. |
| minAgeRestriction | integer | Returns media with an ageRating >= the value given.
|
| maxAgeRestriction | integer | Returns media with an ageRating <= the value given.
|
| minDuration | integer | Returns media with runtime longer than specified duration (in seconds) |
| maxDuration | integer | Returns media with runtime shorter than specified duration (in seconds) |
| minViews | integer | Returns media which have a minimum of the specified started views |
| maxViews | integer | Returns media which have no more than the specified started views |
| minCompletes | integer | Returns media which have a minimum of the specified completed views |
| maxCompletes | integer | Returns media which have no more than the specified completes views |
| minReferenceCount | integer | Returns media which have at most this number of references | maxReferenceCount | integer | Returns media which have at least this number of references |
| statuses | array of strings |
Available statuses are ‘all’, ‘online’, ‘offline’, ‘going_online’, ‘uploading’, ‘processing’, ‘rejected’, ‘review’, ‘review_verify’, ‘failed’. Defaults to ‘online’ - show only online videos. ReturnFields for offline videos are limited to "id" and "status" - all other returnFields will be empty strings. |
| related | integer |
Returns videos which are considered related content to the the supplied media id. |
| references | array of integers |
Returns all videos which reference the supplied media ids. In other words, the video responses of specified videos. |
| tagsBy | string |
specify the login of the user who tags are to be searched against/returned. videos have multiple sets of tags/keywords. By default the video owners tags are used. |
| allowBroadcast | boolean |
Return only videos whose creators have opted to allow their content to be broadcast on tv. |
| allowMobile | boolean |
Return only videos whose creators have opted to allow their content to be distributed via mobile phone. |
| language | string |
Return media with specified language code. |
| preroll | string |
If true restrict videos to ones where users have opted-in to pre-roll advertising. |
returnFields
Takes an array of strings (for example: [’id’, ‘title’, ‘thumbnailUrl’]) allowing you to specify the level of detail returned for media matched by the query.
| id | integer | Id of the media |
|---|---|---|
| title | string | Returns media title |
| owner | string | Returns the owner of the account which posted the media |
| author | string | Returns the author of the video |
| status | string | Returns status of the media. Available statuses are ‘online’, ‘offline’, ‘going_online’, ‘uploading’, ‘processing’, ‘rejected’, ‘review’, ‘review_verify’, ‘failed’. |
| ageRestriction | integer | Age restriction of the video. Returns values 1-5. 1=General, 2=General, 3=13+, 4=17+, 5=17+ explicit |
| publicationDate | ISO 8601 | The publication date of the video |
| modifiedDate | ISO 8601 | The modification date of the video |
| url | string | Returns user specified URL (submitter’s site) that is associated with the video file |
| description | string | Media description |
| keywords | array of strings | Media keywords |
| duration | integer | Media runtime in seconds |
| size | float | QuickTime media file size in MB |
| credits | string | Media credits |
| thumbnailUrl | string | Absolute URL of video thumbnail. Empty string returned if status is not set to online or offline. |
| quicktimeMediaUrl | string | Absolute URL of .mov file for video. Empty string returned if status is not set to online or offline.
This will contain affiliate code for any affiliate passed in during video.find call. |
| quicktimeJsUrl | string |
Absolute path to the src attribute of a script that dynamically renders the Quicktime player. This will contain affiliate code for any affiliate passed in during video.find call. |
| quicktimeDownloadUrl | string |
Direct URL of .mov file for video suitable for downloading the video file. Empty string returned if status is not set to online or offline. This will contain affiliate code for any affiliate passed in during video.find call. |
| flashMediaUrl | string |
Absolute URL to the swf player with necessary parameters included. This will contain affiliate code for any affiliate passed in during video.find call. |
| flashJsUrl | string |
JavaScript URL suitable for inline, embedded flash players with media and affiliate ids included. This will contain affiliate code for any affiliate passed in during video.find call. |
| views | integer | The number of times the video was requested from Revver servers (also known as a view start), publicly available to any user |
| completes | integer | The number of times the video has had a complete view, publicly available to any user |
| affiliateId | integer | The id of the affiliate. if there is no affiliate, returns an empty string |
| chosenThumbnail | integer (0-15) | Returns the number of the thumbnail the creator currently has selected. If no thumbnail has been selected, 0 is returned. |
| references | integer | Returns the id of the video this video references (the video to which this video was a response), or zero if it doesn’t reference any videos. |
| referenceCount | integer | the count of all video's that are referencing this video. |
| language | string | The language code of the media. |
| slug | string | Slugified version of the video's title, suitable for use in URLs. This is helpful for SEO and contextual ad targeting. |
| preroll | boolean | Can be shown with a preroll ad. |
| allowBroadcast | boolean | Can be broadcast on tv. |
| allowMobile | boolean | Can be distributed via mobile phone. |
advanced returnFields
Advanced return fields provide options to allow you to modify the result. They are requested by specifying a 2 element tuple: (fieldName, options).
| Media Urls | The 5 media urls 'quicktimeMediaUrl', 'quicktimeJsUrl', 'quicktimeDownloadUrl', 'flashMediaUrl' and 'flashJsUrl' take the following optional arguments: | |
|---|---|---|
| affilate(optional) | string|integer | login, or user id of the user you would like to affilite the url to. This overrides the global affilate option. |
| name(optional) | string | the key name to use for this url, in the return results. if not supplied, defaults to MEDIAURL for the first url requested, and MEDIAURL-<number> for each additional url requested. |
| Thumbnail Urls | ('thumbnailUrl', options): allows you to request the url for a thumbnail with a custom width or height, or to select a non-default thumbnail. available options are: | |
| width(optional) | integer | width of the thumbnail |
| height(optional) | integer | height of the thumbnail. |
| frame(optional) [1 - 15] | integer | selects which thumbnail to view. if not supplied the thumb selected by the creator will be shown. |
| name(optional) | string | the key name to use for this thumbnail, in the return results. if not supplied, defaults to thumbnailUrl for the first thumb requested, and thumbnailUrl- |
options
The following are optional parameters available in the video.find method call
| limit | integer | Limit the number of results returned to this number - same effect as “LIMIT” keyword in SQL. There is currently a hard maximum limit of 500. |
|---|---|---|
| offset | integer | Skip the first specified number of results - same effect as “OFFSET” keyword in SQL |
| count | boolean | Option of whether to include a count of the total results that would have been returned ignoring the supplied limit/offset. Default is False. |
| orderBy | [string, bolean] | Returns media ordered by the field specified. If the supplied boolean is True, the results will be in ascending order, otherwise in descending order.
Available sort fields are:
|
| affiliate | string|integer | login or user id to affliate return fields to. All urls returned will be stamped to be affiliated with the user specified. If no affiliate is supplied urls will return unaffiliated urls by default. this will be overridden if the affiliate is set in the options argument of if the affiliate specified in the advanced media url return fields. |
| final | boolean | If set to true, returns a boolean as to whether there are no more results. Used in conjunction with offset, this is a useful way to retrieve "paged" results, or a complete resultset as needed. Default is False. Note: using final alters the default return formatting. Instead of the result being an array, the result will have a key/value pair for "final", "result" (and "count" if used). See API Overview for more details. |
return
If the supplied count option and final option is false, an array of details defined by the returnFields specified is returned for each media matched.
If count is True a tuple(two element array) is returned: (count, [viddetails, …])
If final is set to True, then a dictionary(array of key/value pairs) a returned with the keys:
Empty string returned for movUrl, downloadUrl, thumbnailUrl if status is ‘pending’ or ‘processing’.
errors
In addition to the global API errors, this function can return the following local errors:
| 2000 | Search backend is not available - raised when attempting to search an api which does not have a full text indexer configured. |
|---|
open.video.get
This is a shortcut to calling open.video.find with a single id. There will always be only one result returned, but it will still be in an array. There are no options for this function.
open.video.get(id, returnFields)
parameters
| id | Integer | The id of the video. |
|---|
returnFields
The returnFields are the same as those for open.video.find.
errors
The errors are the same as those for open.video.find.
open.collection.find
Returns collections which match the supplied query filter.
open.collection.find(query, returnFields [,options])parameters
| query | object | Filter requirements for collections returned |
|---|---|---|
| ids | array of integers | Returns collections with these ids |
| owners | array of strings | Returns collections with these owners |
| names | array of strings | Returns collections with the given names. Names are matched case insensitive |
| types | array of strings | Possible values: video, user, collection Returns collections of the specified type only |
| subtypes | array of strings | Returns collections of specified subtypes |
returnFields
Specifies the level of detail returned for collections matched by the query.
| id | integer | Id of the media |
|---|---|---|
| owner | string | Owner of the collection |
| name | string | Name of the collection |
| type | string | Type of collection (video, user, collection) |
| subtype | string | Arbitrary subtype |
| description | string | Description of the collection |
| query | object | Object suitable for passing to collection.find / video.find / user.find that describes the contents in this collection |
| restrictions | integer | 0 = no restrictions 1 = can edit, but not delete 2 = can’t edit or delete |
| count | integer | Number of items in the collection |
options
| limit | integer | Limit the number of results returned to this number - same effect as “LIMIT” keyword in SQL. There is currently a hard maximum limit of 20. |
|---|---|---|
| offset | integer | Skip the first specified number of results - same effect as “OFFSET” keyword in SQL |
| count | boolean | Option of whether to include a count of the total results that would have been returned ignoring the supplied limit/offset. Default is False. |
| orderBy | array (string, boolean) | Return collections ordered by the field specified. If the supplied boolean is True, the results will be in ascending order, otherwise in descending order.
Available sort fields are:
|
returns
If the supplied count option is false, an array of details defined by the returnFields specified is returned for each collection matched. If count is True a tuple is returned: (count, [viddetails, …])
open.collection.get
This is a shortcut to calling open.collection.find with a single id. There will always be only one result returned, but it will still be in an array. There are no options for this function.
open.collection.get(id, returnFields)
parameters
| id | Integer | The id of the collection. All collections have a unique ID, regardless of type. In open.collection.collect, the only types that are valid are collections of videos and collections of collections of videos. |
|---|
returnFields
| The returnFields are the same as those for open.collection.find. |
errors
| The errors are the same as those for open.collection.find. |
open.collection.collect
Has the same effect as calling open.video.find, or open.collection.find according to the collection type, with the query set for this collection.
open.collection.collect(id, returnFields [,options])parameters
| id | Integer | The id of the collection. All collections have a unique ID, regardless of type. In open.collection.collect, the only types that are valid are collections of videos and collections of collections of videos. |
|---|
returnFields
| returnFields are based on the type of collection. In open.collection.collect, the only types that are valid are collections of videos and collections of collections of videos, so the only valid returnFields would be those from open.video.find, or those from open.collection.find. |
options
| options are based on the type of collection. In open.collection.collect, the only types that are valid are collections of videos and collections of collections of videos, so the only valid options would be those from open.video.find, or those from open.collection.find. |
errors
In addition to the global API errors, this function can return the following local errors:
| 1100 | Invalid collection id |
|---|