Revver Developer Center: Api : Methods : Video

Revver Developer Center

XML-RPC API.Methods: Video

This Page
Related Pages


video.find

Returns videos matching query and options specified. This is the basic library search method.

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
Returns media which matches on all of the outer list and any of the inner list of keywords.

For example:
[’funny’, ‘dog’] matches videos that have both ‘funny’ and ‘dog’ keywords.

[’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.
ratingsBy string

by default ratings, minRatingCount etc use ratings as taken from the currently authed user. when ratingsBy is provided, all ratings related query options use ratings as taken by the supplied user login. if the login is 'revver' the ratings will be those taken by revver on http://revver.com

minAgeRestriction integer Returns media with an ageRating >= the value given.

  • 0=Unrated
  • 1=General
  • 2=General
  • 3=13+
  • 4=17+
  • 5=17+ explicit
  • Default is 1.
maxAgeRestriction integer Returns media with an ageRating <= the value given.

  • 0=Unrated
  • 1=General
  • 2=General
  • 3=13+
  • 4=17+
  • 5=17+ explicit
  • Default is 5.
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
minRatingAverage float Returns the media that have a minimum average rating taken by authenticated user
maxRatingAverage float Returns the media that have a maximum average rating taken by authenticated user
minRatingSum float Returns the media that have at least this sum of all user ratings taken by authenticated user
maxRatingSum float Returns the media that have at a maximum sum of all user ratings taken by authenticated user
minRatingCount integer Returns media with a minimum number of votes / ratings taken by authenticated user
maxRatingCount integer Returns media with a maximum number of votes / ratings taken by authenticated user
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 not owned by the authed user or a child of the authed user 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
rating object An object with the average, sum, and count ratings of the media scoped to the authenticated user.
average float Average rating given by all clients who have voted through this authenticated user for this media.
sum float Sum of all the ratings by all clients who have voted through this authenticated user for this media.
count integer Number of clients who have voted through this authenticated user for this media.
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 URL will contain the affiliate code of the authenticated API user or to 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 URL will contain the affiliate code of the authenticated API user or to 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 URL will contain the affiliate code of the authenticated API user or to affiliate passed in during video.find call.
flashMediaUrl string

Absolute URL to the swf player with necessary parameters included.

This URL will contain the affiliate code of the authenticated API user or to affiliate passed in during video.find call.
flashJsUrl string

JavaScript URL suitable for inline, embedded flash players with media and affiliate ids included.

This URL will contain the affiliate code of the authenticated API user or to 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
revenue float The amount of revenue generated by the specified video for the authenticated user -- i.e. amount of syndication revenue earned if the video belongs to another user, the total amount earned if video owner makes the call
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- for each additional thumb requested.

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:

  • publicationDate
  • modifiedDate
  • createdDate
  • title
  • author
  • views
  • completes
  • ratingCount
  • ratingSum
  • ratingAverage
  • duration
  • size
  • revenue (only available to owner)
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 it's assumed urls should be affiliated to the authed user. system accounts 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:

  • result: video details
  • final : Boolean : True if this is the last of the results, False otherwise
  • count : Integer : number of results that match the query, ignoring limit. Only supplied if the count option is set to true.

    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:

    1105 invalid ratingsBy login
    2000 Search backend is not available - raised when attempting to search an api which does not have a full text indexer configured.

    video.get

    This is a shortcut to calling 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.

    video.get(id, returnFields)

    parameters

    id Integer The id of the video.

    returnFields

    The returnFields are the same as those for video.find.

    return

    Returns a array containing the requested returnFields.

    errors

    The errors are the same as those for video.find.

    video.getUploadTokens

    Before uploading a file to the upload server, a token must be requested. Once you have a token you can upload media to the upload server by posting to the string + the token returned by this method call (sting/token). Additionally, the upload server accepts a queryString of urlRedirect - which accepts a URL to redirect the page to after successful completion of the file post.

    The token is also used when first creating the video with its initial metadata with video.create.

    video.getUploadTokens(count [,options])

    parameters

    count integer Number of upload tokens to issue.

    options

    owner string Optional.
    The login of the child user that should own the media. If left empty, the file will become the authenticated user’s upload.

    example

    Error: cannot read infile: [Errno 2] No such file or directory: '/var/www/developer.revver.com/files/code/api_xml_video_find.py'

    return

    Returns a array with a string and array of strings, containing the requested tokens.
    String returned is the URL to upload the media to.
    Array of strings contains the requested tokens.

    errors

    In addition to the global API errors, this function can return the following local errors:

    1100 Invalid owner

    video.create

    Creates a video for the upload that corresponds to the supplied token.

    video.create(id|token, title, keywords, ageRestriction [,options])

    parameters

    id|token Required.
    Accepts either the id or the token for the media to be created.
    id integer Id of the video. Useful for using after searching for videos that have yet to have their metadata set.
    token string Token of the upload that corresponds to this video. See video.getUploadTokens
    title string Title of the media
    keywords array of strings Required.
    Keywords for the media. At least one keyword must be supplied. Keywords cannot be empty strings, but can contain spaces.
    ageRestriction integer Required.
    Recommended age restriction for the video. 1=General, 2=General, 3=13+, 4=17+, 5=17+ explicit.

    options

    credits string Credits for the media, defaults to empty string
    url string URL associated with the video
    description string Description of the media file
    author string Author of the video
    language string The language code of the media.
    preferOffline boolean If True, the media will be in Offline status after passing review. If False or not provided, the media will be in Online status after passing review.
    references Integer id of the video this video references. This can be used in conjunction with video.find to create "video responses".

    returns

    Returns the id of the newly created media

    errors

    In addition to the global API errors, this function can return the following local errors:

    1100 Invalid token
    1101 Insufficient permissions to create media for token
    1103 create has already been called for token
    1105 cannot reference the video being created
    1106 cannot reference a deleted video
    1107 cannot reference an invalid video
    1112 tag is longer than 30 chars
    1113 no more than 30 tags per video

    video.count

    Count the number of results a query would return ignoring any offset / limit numbers

    video.count(query)

    parameters

    query object See video.find

    return

    the number of items matched by the query.

    video.rate

    Rate a specified media file. Ratings will be applicable only to authenticated user and children.

    video.rate(id, client [,rating])

    parameters

    id integer Required.
    Id of the video to rate
    client

    		string

    		Required.
    A string which uniquely identifies the client making the rating. For example, IP address. If the client supplied has already rated the given video, the previous rating made by that client is overwritten.
    rating

    		float

    		Optional.
    The rating supplied by the client - optionally supplied. The client’s rating is only updated if supplied

    return

    An object with the following fields are returned:

    rating float Last rating made by this client
    average float Average rating given by all clients who have voted through this user for this media
    sum float Sum of all the ratings by all clients who have voted through this user for this media
    count integer Number of clients who have voted through this authenticated user for this media

    errors

    In addition to the global API errors, this function can return the following local errors:

    1100 Invalid mediaId

    video.report

    Returns detailed statistics for videos that match the supplied query.

    video.report(query, metrics, [options])

    Deprecated

    This method is no longer supported.

    video.update

    Updates the details of a video. A video can only be updated if its currently in the offline or online state. Only videos own by the authenticated user or their children can be updated.

    video.update(id, options)

    parameters

    id integer Required.
    Id of the video to update

    options

    title string Title of the media
    keywords array of strings Keywords for the media. At least one keyword must be supplied. Keywords cannot be empty strings, but can contain spaces
    credits string Credits for the media, defaults to an empty string
    url string URL associated with the video (submitter’s site)
    description string Description of the media file
    author string Author of the video
    status string New status of the video. Status can be ‘offline’ or ‘online’
    thumbnail integer
    (1-15)    		 Sets the default thumbnail url to one of the 15 thumbnails captured during the transcoding process. (Thumbnails are offset by +1, so thumbnail[1] -> thumb_0)
    references integer id of the video this video references. This can be used in conjunction with video.find to create "video responses".

    return

    True on success.

    errors

    In addition to the global API errors, this function can return the following local errors:

    1100 Invalid mediaId
    1101 insufficient permission to update media id
    1102 can't update state until video is online or offline
    1104 cannot update video with status 'rejected'
    1112 tag is longer than 30 chars
    1113 no more than 30 tags per video

    video.tag

    Adds Tags to a video. Tags can be associated to the authenticated user, a child user, or the owner of the video.

    any of the following characters are removed from tags - '"','?', ')', '(', ':', ',', '!', '\, '<', '>', ';', '~', '{', '}', '.'

    The following characters are stripped , i.e. only removed if they begin or end a tag (done repetitively, so several of them beginning or ending or both will all be removed). '-','_'

    Tags are added to the "keywords" field, but only accessible when using the "tagsBy" query term in video.find();

    video.tag(id, tags, [options])

    parameters

    id integer Required.
    Id of the video to tag
    tags array of strings Required.
    Array of tags (up to 30 MAX)

    options

    login string the login of the user to tas as. If omitted, the video is tagged by it's owner. You may only tag as a particular login if it is you, or you are its parent.

    return

    True on success.

    errors

    In addition to the global API errors, this function can return the following local errors:

    1109 Invalid login
    1111 Insufficient permissions to tag as this login
    1112 tag is longer than 30 chars
    1113 no more than 30 tags per video
    1114 No valid tags remain after removing illegal characters

    video.statuses

    Returns key/value pairs for all valid video statuses for a given user.

    video.statuses(owner)

    parameters

    owner string Required.
    A valid username

    return

    A set of key/value pairs which provides a look up from status to a count of the number videos the owner has in this status.

    errors

    In addition to the global API errors, this function can return the following local errors:

    1101 Invalid owner

    video.delete

    Deletes the specified videos. Only videos own by the authenticated user or their children can be deleted.

    video.delete(ids)

    parameters

    ids array of integers Required.
    Ids of the videos to delete. This action is not undoable.

    return

    True on success.

    errors

    In addition to the global API errors, this function can return the following local errors:

    1100 Invalid mediaId
    1101 Insufficient permissions to delete mediaId