Query API (Deprecated)

To request information about content in a Backlot account, we offer a flexible query API.

Note: This software is deprecated. Use the latest version.

Requests are made through REST-style signed GET requests to http://api.ooyala.com/partner/query. Results are paginated with the page size set by the limit parameter and the requested page number set by the pageID parameter. When nextPageID has a value of -1, there are no further results to fetch.

Required search criteria parameters:

  • pcode – Account Identifier
  • expires – Query expiration date in seconds since epoch (00:00:00 1/1/1970 GMT)
  • signature – The digital signature of the request. The signature should be calculated using SHA-256 with the signature generation rules.

Optional search criteria parameters:

  • contentType – Search by content type. One of Video, VideoAd, Channel, MultiChannel, LiveStream, YouTube or RemoteAsset.
  • description – Search by words in the description.
  • title – Search by words in the title. 'LIKE' matching is used à la SQL.
  • text – Search by words in title or description. Search results include content with specified words in the title or in the description.
  • embedCode – Match against embedCode. Multiple embedCode matches can be specified by using a comma-separated list.
  • fields – a comma-separated list of additional fields to include in the results. Valid values for this list are:
    • labels
    • metadata
    • ratings – The ratings information is returned in a "movieRatings" XML element of the form: <movieRatings>4;3;2;0;0;0;0;0;0;0;0</movieRatings>. This element will be absent if the content item has no ratings yet.
    Note: Labels will be included in the response if a label is included in the search parameters; the same is true for metadata.
  • includeDeleted – true or false. Specify whether or not to include content that has been deleted in the last 30 days in the query response.Defaults to false.
  • label[<id>] – Match content having labels with fully-qualified names matching ALL given strings. Use alphanumeric characters for "id" portion of parameter.
  • limit – The number of results to include per page. Default is 500.
  • pageID – The ID of the requested page. Default is 0.
  • queryMode – The operator to use when evaluating multiple search criteria. This can be either "AND" or "OR". The default is AND.
  • statistics – A comma-separated list specifying the time period of statistics to return. Specify one or more from lifetime, 1d, 2d, 3d, 4d, 5d, 7d, 14d, 28d, 29d, 30d, 31d
  • status – Match content status. Multiple status matches can be specified using a comma-separated list.
    • RemoteAsset – remote asset
    • deleted – video or channel removed from the system
    • live—video or channel is error-free, processed, and can currently be played
    • scheduled—video or channel is error-free, processed, and is scheduled to be available sometime in the future
    • finished airing—video or channel is error-free, processed, and no longer available
    • error – pre or post processing error
    • filemissing – upload stage error
    • uploading – file is currently being uploaded
    • paused – video cannot be played (user set state)
    • uploaded – state between uploading and processing
    • na – represents unknown content
    • removed – auto-syndicated content which has been deleted and is no longer available in the destination account because it was deleted in the source account
    • uploading – 'a' here represents API, so this means it is an API upload. Every upload that does not occur through a Backlot interface is an API upload.
    • auploaded – reference auploading, above
    • duplicate – a duplicate file that we detected based off of name and file size within a particular account
    • pending – state that is practically the same as 'paused' but is named differently to denote that a moderation process of sorts is occurring
    • processing – video is going through processing
  • updatedAfter – Find content that was updated after some date. Specify the date in seconds since epoch (00:00:00 1/1/1970 GMT).
  • orderBy – Two different sort options can be specified: uploadedat or updatedat which correspond to when the asset was uploaded and last updated respectively. The order is specified by asc or desc. As an example, if one wanted to order the results in descending order by upload time: orderBy=uploadedAt,desc.
Note: If multiple search parameters are specified, a valid match must satisfy all the parameters.

Query Result

The result of a query is an XML document served as a response body. The root tag is <list>, and all matching content elements are included as <item> tags in that list. An example result follows in the next section.

Possible Query Result Data Fields:

  • embedCode: Embed code for the given content
  • title: Title of the content, if applicable
  • description: Description of the content, if applicable
  • status: Status of the content
  • hostedAt: The URL for the main page the video or channel is embedded on, if applicable
  • remoteAssetURL: The underlying URL of the remote asset, if applicable
  • error: Processing error.
  • content_type: One of Video, VideoAd, Channel, Alias, AliasAd, MultiChannel, Autosynd
  • uploadedAt: Upload time, in seconds since epoch (00:00:00 1/1/1970 GMT)
  • length: Length of video, in milliseconds
  • size: Original video size in bytes
  • updatedAt: Last updated time, in seconds since epoch (00:00:00 1/1/1970 GMT)
  • flightStartTime: The start time for an asset comes from the syndication group to which it is assigned unless you override this by settings in the Backlot UI. If you overrid, the start time is based on what you set on the asset (which defaults to the movie's upload time).
  • flightEndTime: Video cannot be played after this time, in seconds since epoch (00:00:00 1/1/1970 GMT)
  • width: Original video width in pixels
  • height: Original video height in pixels
  • labels: The labels associated with the content. Note that this section will only be included if a label was part of the search criteria, or the parameter "fields=labels" was specified.
  • metadata: All of the name/value pairs associated with the content. Note that this section will only be included if a metadata field was part of the search criteria, or the parameter "fields=metadata" was specified.
  • ratings: the ratings associated with this piece of content. Returns an array of 11 integers where each integer indicated the number of times a particular rating was given to this item. For example, [0, 16, 0, 0, 0, 0, 0, 0, 25, 0, 0] indicates that the item has 16 votes for "1" and 25 votes for "8".
  • thumbnail: Default thumbnail information including height, width, and URL
  • stat: If requested, returns duration-specific blocks containing statistical information including displays, plays, rewinds, playtime, and watched
Note: Internal statuses exposed via the Query API may be slightly different from the statuses presented in the Backlot user interface.

Example of Query Result

<?xml version="1.0" encoding="UTF-8"?>
<list totalResults="277" nextPageID="10" size="2" statistics-as-of="1247507998"
 statistics-as-of_text="Mon Jul 13 17:59:58 UTC 2009" limit="2" pageID="9">
    <metadataItem name="director" value="Francis Ford Coppola"/>
    <metadataItem name="actor" value="Marlon Brando"/>
  <thumbnail height="79" width="106">
      <displays total="0"/>
      <plays total="0"/>
      <rewinds total="0"/>
      <playtime ms="0"/>
      <watched _25="0" _50="0" _75="0" _100="0"/>