Labels

When added to external publishing targets, labels specify which videos, channels, and channel sets to publish externally. Additionally, labels are also useful for organizing your video library, searching for videos, and retrieving targeted analytics.

Note: For more information about Backlot REST API commands, see the Backlot API Reference.

Create a Label

[POST]/v2/labels{ 
   properties
} 

Create multiple labels using full label name

The full paths of labels must be CGI-escaped (URL-encoded) - they must begin with a leading forward slash ("/") as a delimiter to define the level in the label hierarchy, and comma (",") as a delimiter to support the creation of multiple hierarchal labels. All components of the path are created using this method.

Note:

If a label specified in a request already exists, the system returns the identifier and other information about that pre-existing label. For example, if your request contains two new labels and two that already exist, the two new labels are created. The identifiers and other information for all four labels are returned in the response.

If there are multiple labels with the same full path name (for example, two labels with the exactly same full path name "/a/b/c"), and you try to create a label with the full path name "/a/b/c/d", the system responds with error 400 because it does not know which "/a/b/c" to use.

[POST]/v2/labels/by_full_path//full/path/label1,/full/path/label2,...

You can also use a leading slash and a comma as delimiters in your label names but in that case you MUST ALSO USE tilda ("~") as an escape character in combination to the slash/comma. This is required so that the system would "know" if the slash/comma escape characters are used for hierarchy levels and multiple labels, or for delimiting label names within the same label path definition. For instance:

[POST]/v2/labels/by_full_path//sports/football/NFL~,soccer,/animal%20videos/buffaloes~/horses
[
  {
    "name" : "NFL,soccer",
    "id" : "1ac6255456ba41c8860a3a32bfd1bb7e",
    "parent_id" : "dba57e8e48414613aeb471fe0a3228c8",
    "full_name" : "/sports/football/NFL,soccer"
  },
  {
    "full_name" : "/animal videos/buffaloes/horses",
    "parent_id" : "c93e078454304c05a5182c7eb3017911",
    "id" : "3206f660f49e4badb891d18c3b5c4fac",
    "name" : "buffaloes/horses"
  }
]
In this example:
  • The first full path definition in the request URL creates a label with a comma (,) in it using tilda ("~") as an escape character before the comma: NFL~,soccer
  • The second full path definition creates a label with a forward slash ("/") in it using tilda ("~") as an escape character before the slash: buffaloes~/horses

List Labels

[GET]/v2/labels

List All Top-level Labels

[GET]/v2/labels?is_root=true

Get assets assigned to a label

[GET]/v2/labels/label_id/assets

View Label Information

[GET]/v2/labels/label_id

View All Sub-labels Associated With a Label

[GET]/v2/labels/label_id/children

View Label Information by Full Path Names

The full paths of labels must be CGI-escaped (URL-encoded) - they must begin with a leading forward slash ("/") as a delimiter to define the level in the label hierarchy, and comma (",") as a delimiter to support the creation of multiple hierarchal labels.

The services returns 400 if any paths do not exist. The response body states which components of the paths already exist or are missing.

[GET]/v2/labels/by_full_path//full/path/label1,/full/path/label2

You can also delimit label names in your request using a leading slash or comma, but in that case you must also use tilda ("~") as an escape character in combination to the slash/comma. This is required so that the system would "know" if the slash/comma escape characters are used for hierarchy levels and multiple labels, or for delimiting label names within the same label path definition. For instance:

[GET]/v2/labels/by_full_path//sports/football/NFL~,soccer,/animal videos/buffaloes~/horses
{
  "items" : [
    {
      "id" : "1ac6255456ba41c8860a3a32bfd1bb7e",
      "full_name" : "/sports/football/NFL,soccer",
      "name" : "NFL,soccer",
      "parent_id" : "dba57e8e48414613aeb471fe0a3228c8"
    },
    {
      "full_name" : "/animal videos/buffaloes/horses",
      "name" : "buffaloes/horses",
      "parent_id" : "c93e078454304c05a5182c7eb3017911",
      "id" : "3206f660f49e4badb891d18c3b5c4fac"
    }
  ]
}
In this example, multiple labels are retrieved based on the following label full path definitions:
  • The first full path definition in the request URL returns a label with a comma (,) in it using tilda ("~") as an escape character before the comma: NFL~,soccer
  • The second full path definition returns a label with a forward slash ("/") in it using tilda ("~") as an escape character before the slash: buffaloes~/horses

Delete a Label

[DELETE]/v2/labels/label_id

Route Attributes

The following table describes all attributes that can be expressed through the route.

Route Attribute Description
label_id

The ID of the label. To get a list of labels, perform a get against the /v2/labels route.

Type: String

Default: None

Example: /labels/r28ertfe44ea4e648fd07d4509123254 b

Query String Parameters

The following table describes all parameters that can be expressed through the route.

Parameter Description
is_root

Retreives all top-level labels.

Type: Boolean

Default: If is_root is not specified, default value is false.

Example: /v2/labels?is_root=true

Properties

The following table describes all properties that can be associated with a label.

Property Description Required?
asset_count

Read-only. Specifies the number of assets using the label. Returned when you make a get request against a specific label ID.

Type: Integer

Example: 42

No
full_name

Full path to the label, including any parents.

Type: String

Example: "/Sports/Motorcycle Racing"

Yes
id

Read only. ID of a label.

Type: String

Example: "814efb109416490a98ee3f4fcd673244"

Yes
items

Array containing labels. Returned by a get request to /v2/labels.

Type: Array

Example: n/a

No
name

Name of a label. To use non-Latin characters, make sure they are UTF-8 and URI-encoded.

Type: String

Example: "Motorcycle Racing"

Yes
parent_id

ID of the parent label.

Type: String

Condition: Required when adding a child label to a parent label.

Example: "Sports"

Conditional

Best Practices for Labels

The following best practices will ensure that you have optimal performance and speed in Theme Builder.
  • Limit the use of excess labels in your Backlot account as a low this will keep load times low in Theme Builder.
  • Create broad and categorical labels as labels that apply to only 1 or 2 movies will result in many labels that are of limited usefulness.

Examples

This section provides additional examples on using the labels API.

This example creates a top-level label:

[POST]/v2/labels{  
   "name":"Hobbies"
}

Backlot returns a response similar to the following:

{
   "name":"Hobbies",
   "id":"d5751b77a0c24972888bf906734d4522",
   "full_name":"/Hobbies",
   "parent_id":null
}
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

This example adds a child label to a parent label:

[POST]/v2/labels{  
   "name":"Hockey",
   "parent_id":"d5751b77a0c24972888bf906734d4522"
}

Backlot returns a response similar to the following:

{  
   "name":"Hockey",
   "id":"85042f300fc143c093e8f4ee01894355",
   "full_name":"/Hobbies/Hockey",
   "parent_id":"d5751b77a0c24972888bf906734d4522"
}
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.
This example creates multiple labels, specified by their full path names, in a single call.
[POST]/v2/labels/by_full_path//sports/football/NFL,/animal videos/buffaloes
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.
This example creates multiple labels with combined label names, specified by their full path names, using tilda ("~") as an escape character before the slash/comma delimiting the label names, in a single call.
[POST]/v2/labels/by_full_path//sports/football/NFL~,soccer,/animal%20videos/buffaloes~/horses
[
  {
    "name" : "NFL,soccer",
    "id" : "1ac6255456ba41c8860a3a32bfd1bb7e",
    "parent_id" : "dba57e8e48414613aeb471fe0a3228c8",
    "full_name" : "/sports/football/NFL,soccer"
  },
  {
    "full_name" : "/animal videos/buffaloes/horses",
    "parent_id" : "c93e078454304c05a5182c7eb3017911",
    "id" : "3206f660f49e4badb891d18c3b5c4fac",
    "name" : "buffaloes/horses"
  }
]
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

This example lists all labels:

[GET]/v2/labels

Backlot returns a response similar to the following:

{  
   "items":[  
      {  
         "name":"Sports",
         "id":"814efb109416490a98ee3f4fcd6784cf",
         "parent_id":null,
         "full_name":"/Sports"
      },
      {  
         "name":"Motorcycle Racing",
         "id":"bace921fdea44cc18a5a273155514522",
         "parent_id":"814efb109416490a98ee3f4fcd673244",
         "full_name":"/Sports/Motorcycle Racing"
      },
      {  
         "name":"Hockey",
         "id":"85042f300fc143c093e8f4ee01894355",
         "parent_id":"d5751b77a0c24972888bf906734d8c34",
         "full_name":"/Hobbies/Hockey"
      },
      {  
         "name":"Hobbies",
         "id":"d5751b77a0c24972888bf906734d4522",
         "parent_id":null,
         "full_name":"/Hobbies"
      }
   ]
}
Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.

This example deletes a label:

[DELETE]/v2/labels/85042f300fc143c093e8f4ee01894355

Backlot returns a 200 response.

Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad.
https://help.ooyala.com/sites/all/libraries/dita/en/video-platform/api/labels.html

Was this article helpful?