Working with Labels

Introduction

Labels are similar to tags. You can add them to videos and then use them to search for a group of videos or but they have some distinct advantages:

• Labels are created at the account level, and applied to videos.

  This is important particularly if your purpose is to organize your video library.For example, if you are trying organize your videos using tags, you might create tags like birds, fish, and insects. Then it's easy to search and find all your bird videos and create a smart playlist for them. But if a user adding a new video accidentally types bird instead of birds, you now have a new tag, and the video does not belong to your birds collection.

  If you create a label called birds instead, only that label can be added to a video. You cannot accidentally add the non-existent label birds instead.

• Labels are created as hierarchical path, such as /nature/birds/shore_birds.

  This means that you can search (or create a playlist based on) a partial or full path:

  • q=labels:/nature - returns all videos that have the label nature
  • q=labels:/nature/birds - returns the birds sub-group of the nature videos
  • q=labels:/nature/birds/shore_birds - returns the shore_birds sub-group of the /nature/birds videos

Creating and managing labels

Labels for your account can be created and managed using the CMS API /v1/accounts/{{account_id}}/labels endpoints.

Note that all the API endpoints shown below would be appended to the CMS base URL:

https://cms.api.brightcove.com

Creating a label

New labels can be created by sending the full path in a POST request:

Sample request endpoint

/v1/accounts/1234567890/labels

Sample request body

{
        "path": "/nature/birds/shore_birds/"
        }

Note that all labels in the path that do not already exist will be created. If you want to add another group of forest_birds, you would send:

{
        "path": "/nature/birds/forest_birds/"
        }

This time, only the forest_birds sub-label, will be created, since nature and birds already exist.

Similarly, if you want to add a new sub-group sandpipers to shore_birds, you would send:

{
        "path": "/nature/birds/shore_birds/sandpipers"
        }

Sample response

{
        "path": "/nature/birds/shore_birds/sandpipers/"
        }

Getting labels

You can get all the labels for an account by sending a GET request:

Sample request endpoint

/v1/accounts/1234567890/labels

Sample response

{
        "account_id": "57838016001",
        "labels": [
        "/nature/birds/",
        "/nature/birds/shore_birds/",
        "/nature/birds/forest_birds/",
        "/nature/mammals/seamammals/"
        ],
        "version": 4
        }

Updating a label

To update a label, you send a PATCH request to:

/v1/accounts/{{account_id}}/labels/by_path/{path}

Sample request endpoint

/v1/accounts/1234567890/labels/by_path//nature/birds/shore_birds

Sample request body

{
        "new_label": "coastal_birds"
        }

Note that the new_label value will replace the last item in the {path} included in the request. So if instead you wanted to replace /birds with /avian, the request and body would look like this:

Endpoint

/v1/accounts/1234567890/labels/by_path//nature/birds/

Request body

{
        "new_label": "avian"
        }

After this request, the coastal_birds path would become /nature/avian/coastal_birds. The path would change for any addition sub-labels in the hierarchy, so /nature/birds/forest_birds would become /nature/avian/forest_birds

The response will include the number of labels that were updated.

Sample response

{
        "path": "/nature/avian",
        "labels_updated": "2"
        }

Delete a label

Deleting a label uses a DELETE request sent to the same endpoint as the update request. Only the path ending with that sub-label (and paths that have additional sub-labels) will be deleted, while higher-level labels are retained.

For example, say you have these three label paths:

        /nature/wildlife/avian/coastal_birds
        /nature/wildlife/avian/coastal_birds/sandpipers
        /nature/wildlife/avian/forest_birds
      

Sending a DELETE request to /v1/accounts/1234567890/labels/by_path//nature/wildlife/avian/coastal_birds would delete the first paths above, but it would not affect the third one.

Adding and updating labels to videos

Add labels to videos as an array of full label paths:

[
        "/nature/wildlife/avian/coastal_birds",
        "/nature/wildlife/avian/coastal_birds/sandpipers"
        ]

The labels array can be included in a create video (POST) request or an update video (PATCH) request.

To update the video labels, send the full, updated videos array in a update video (PATCH) request. So, for example, to add the /nature/wildlife/avian/forest_birds, you would send the array:

[
        "/nature/wildlife/avian/coastal_birds",
        "/nature/wildlife/avian/coastal_birds/sandpipers",
        "/nature/wildlife/avian/forest_birds"
        ]

Searching for videos by labels

You can search for videos by labels just as you can other fields that are supported for searching. As mentioned in the introduction, adding sub-labels to the search path filters the search results:

Limitations

• A maximum of 10,000 labels can be added to an account
• Labels can only be managed using the API. There is currently no option in the UI
• Searching by labels is currently supported by the v1 search syntax only
• Labels are not included in the video metadata that is shared to an affiliate using Media Sharing.