Query Construction

To limit the amount of data returned in a GET call, you can specify where queries.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.
Note:
  • Flight times (date/time restrictions with the start_date, end_date, start_time, and end_time properties) might also be restricted by publishing rules. However, the Query API looks at flight time restrictions only of the asset itself.
  • Because assets with no date restrictions are playable during a specified period of time, they are also returned in the results.
  • You cannot query for null values.
Note: Make sure non-ASCII letters and ' characters are escaped.

Query String Parameters

The following table describes all parameters that can be used on the query string.

Parameter Description Required?
and For querying for intersections of labels.
Note: Make sure non-ASCII letters and ' characters are escaped.

Type: String

Default: none

Example: [GET] /v2/assets?where=labels INCLUDES 'Sports' AND labels INCLUDES 'Case Study'

No
include

Returns additional information about the asset.

Type: String

Default: name

Valid Values: metadata | labels

Example: [GET] /v2/assets?include=metadata,labels

No
limit

The maximum number of results to return. If you receive more results than the value you specify, you can get the next page of results with the paging token.

Type: String

Default: 100

Valid Values: 1-500

Example: [GET] /v2/assets?limit=5

No
orderby

The field to sort on.

Type: String

Default: created_at descending order

Valid Values: name | duration | asset_type | created_at

Examples: [GET] /v2/assets?orderby=name, [GET] /v2/assets?orderby=name+DESCENDING

No
page_token
A URL returned by the previous API request that enables you to page through results. If there is no remaining data available to display, no token is returned.
Note:

Type: String

Default: None

Example: [GET] /v2/assets?limit=2&page_token=1332345124%3B0wZTQ4NDpW27FQgXF6zry0b42OI76GZN

No
where

The where clause returns results that meet the specified criteria.

Note: You cannot search for properties with null values.
Note: Make sure non-ASCII letters and ' characters are escaped.

Type: String

Default: name

Example: [GET] /v2/assets?where=description='cat video'

No

About Pattern Matching and Results

The query returns a result for each item that contains all terms. Queries are case-insensitive, return singular and plural versions of the terms, and exclude common words such as "a" and "the" from the search. For example, where=description='Cat videos' returns:

  • "Videos about cats"
  • "Funny video of a cat"
  • "Cats watching videos"
Note: Deleted assets are never returned in query results.

Comparisons

All comparison functions are supported for integer and string fields on assets. (<, <=, =, >=, >, !=). For example, duration>600 returns all assets over 10 minutes (600 seconds).

Intersection of Labels

To find assets that have two or more labels in common, use the and operator. For example, to find assets that have both the label Sports and the label Baseball:
[GET]/v2/assets?where=labels INCLUDES 'Sports' AND labels INCLUDES 'Baseball'
Note: We recommend that you use no more than 3 'labels INCLUDES' in the call.

Examples

This example returns the first two assets that have "cat" and "funny" in the description, and are more than 10 minutes long:

[GET]/v2/assets?where=description='cat funny'+AND+duration>600&orderby=name&limit=2

Backlot returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ],
   "next_page":"/v2/assets?limit=2&page_token=1314306109%3B1saGRyMjoOgjkUSjod_1TQINs_HOQnoU"
}

This example gets a list of assets that match the specified embed codes:

/v2/assets?where=embed_code+IN+('IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt','9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte')

Backlot returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

This example gets a list of assets that have a value of the category metadata key equal to "Cat Videos" :

[GET]/v2/assets?where=metadata.category='Cat Videos'&include=metadata

Backlot generates a feed similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "metadata":{  
            "category":"Cat Videos"            "rating":"G"
         },
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "metadata":{  
            "category":"Cat Videos"            "rating":"PG"
         },
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

This example returns all videos with the "funny" label:

[GET]/v2/assets?where=labels+INCLUDES+'funny'

Backlot generates a feed similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":19000,
         "name":"Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/IzNnllMjphu2XF3_UgPROoCi9B2BwtSg/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-25T15:32:57+00:00",
         "embed_code":"IzNnllMjphu2XF3_UgPROoCi9B2Bwqwt",
         "time_restrictions":null,
         "updated_at":"2011-08-29T23:12:09+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-25 at 08.31.mov",
         "description":"A video of funny cats.",
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":25959,
         "name":"More Funny Cats",
         "preview_image_url":"http://ak.c.ooyala.com/9hcDdkMjq4LUKvPP-vJcgDds_TPIsP0u/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-04-05T21:49:46+00:00",
         "embed_code":"9hcDdkMjq4LUKvPP-vJcgDds_TPIsrte",
         "time_restrictions":null,
         "updated_at":"2011-06-01T23:13:40+00:00",
         "external_id":null,
         "hosted_at":null,
         "original_file_name":"Movie on 2011-04-05 at 14.44.mov",
         "description":"Can there really be more funny cat videos? Yes.",
         "status":"live"
      }
   ]
}

Flight times restrict when content can be played. This example returns assets that were playable for the entirety of June 2011:

[GET]/v2/assets?where=time_restrictions.start_date<='2011-06-01T00:00:00Z'+AND+time_restrictions.end_date>='2011-07-01T00:00:00Z'

Backlot returns a response similar to the following:

{  
   "items":[  
      {  
         "asset_type":"video",
         "duration":3366,
         "name":"My movie",
         "preview_image_url":"http://ak.c.ooyala.com/B5bzAzMzrrnbUrxt_vBj0hLcjgdQSkSH/Ut_HKthATH4eww8X5hMDoxOjBrOw-uIx",
         "created_at":"2011-01-21T23:37:28+00:00",
         "embed_code":"B5bzAzMzrrnbUrxt_vBj0hLcjgdQSkSH",
         "time_restrictions":{  
            "type":"range",
            "start_date":"2011-06-01T00:00:00Z",
            "end_date":"2011-06-15T00:00:00Z"
         }         "updated_at":"2011-11-29T00:40:37+00:00",
         "external_id":null,
         "original_file_name":"My movie.mov",
         "hosted_at":null,
         "description":null,
         "status":"live"
      },
      {  
         "asset_type":"video",
         "duration":0,
         "name":"My other movie",
         "preview_image_url":null,
         "created_at":"2011-01-01T19:40:32+00:00",
         "embed_code":"QycmV4Mjp_iICcP6fhpiHsY81jDgmOUY",
         "time_restrictions":{  
            "type":"range",
            "start_date":"2011-06-015T00:00:00Z",
            "end_date":null
         }         "updated_at":"2011-10-26T19:40:32+00:00",
         "external_id":null,
         "original_file_name":"My other movie.avi",
         "hosted_at":null,
         "description":null,
         "status":"uploading"
      }
   ]
}

해당 내용이 도움 되었습니까?