Setting and Getting Ad Key/Value Pairs with the Media API

The Video object in the Media API has a property named adKeys that you can use to set or retrieve a video's key/value pairs. The adKeys property is a list of key/value pairs, in the usual key=value format.

You can also set a video's key/value pairs using the Advertising module in the Video Cloud Studio, or by using FTP batch provisioning, with the ad-keys attribute in the title element of your FTP batch provisioning manifest.

Getting key/value pairs in a video

To retrieve a video's key/value pairs, simply include adKeys in the video_fields parameter of the Media API Read method you want to use. The video_fields parameter specifies which properties of the Video object should be included in the JSON or MRSS formatted data returned by the Media API Read method. In this example, we retrieve the 5 most popular videos from the last 7 days (starting yesterday), returning the videos' name, reference ID, and key/value pairs:

http://api.brightcove.com/services/library?command=find_all_videos
    &video_fields=name,referenceId,adKeys
    &sort_by=plays_trailing_week&page_size=5&sort_order=DESC
    &token=0Z2dtxTdJAxtbZ-d0U7Bhio2V1Rhr5Iafl5FFtDPY8E.

Setting key/value pairs in a video

To set key/value pairs in a video, include the adKeys property in the Video object you pass in a create_video or update_video method. The values for the adKeys property must be in key=value format, and if you have more than one key/value pair, separate them with commas. The JSON you'd pass in for the create_video method might look like this:

{"method": "create_video",
           "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
                      "video" : {"id":38,"adKeys":["category=budget","species=gibbon","live=false"]
                      "name":"Cookies!","shortDescription":"yumyumyumyum tasty!"},
                      "filename":"miamiMoon.mov",
                      "create_multiple_renditions" : true}}

If you use the update_video method, you overwrite the existing values of any properties you include in the Video object, so if you want to append key/value pairs to the video's existing key/value pairs, make sure you include the existing key/value pairs as well as the new ones in the Video object you pass with update_video.