Setting Custom Metadata with the Media API

Custom metadata is available only for Brightcove Enterprise customers. If you are interested in upgrading your Brightcove account, please contact Brightcove for more information.

After you have set up custom metadata for your Brightcove account, you can set values for the custom metadata fields of your videos. You can set and read metadata for a video using the Media module, FTP batch provisioning, or the Media API. This topic describes how to use the Media API to set and get custom metadata for your videos.

Before you begin

Before you can set custom metadata for your videos, you need to set up the custom metadata fields that you want to be available in your account. Read about how to do this.

Setting custom metadata with Media API Write methods

You set custom metadata for a video using the create_video or update_video methods. The custom metadata is contained in the Video object's customFields property as a set of field name/value pairs. For example, the JSON to create a video with custom metadata fields named genre and rating might look like this:

{"method": "create_video",
 "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
            "video" : {"id":38,"name":"Cookies!","shortDescription":"yumyumyumyum tasty!",
                       "customFields":{"genre":"Martial Arts","rating":"TV-Y7"}},
            "filename":"miamiMoon.mp4",
            "create_multiple_renditions" : true}}

Getting custom metadata with Media API Read methods

When you retrieve a video that includes custom metadata, you can get the custom metadata values by passing the optional custom_fields argument with the names of the fields you want:

command=find_all_videos&custom_fields=genre

The custom fields you ask for will be returned in JSON like this:

"customFields":{"genre":"Martial Arts"}

In addition, you can retrieve all of your custom fields by including customFields as a value in your video_fields argument:

command=find_all_videos&video_fields=name,shortDescription,customFields

If the given custom field doesn't have a value, it won't be returned. For example, if you have two custom fields, named "fruit" and "vegetable", and "fruit" is set to "kumquat" and "vegetable" is set to "null", the values returned for video_fields=customFields would be:

{"fruit":"kumquat"}

and not:

{"fruit":"kumquat","vegetable":null}