Using the CMS API: Add Geo-Filtering

Product(s)
Video Cloud
Role(s)
API Developer
Task(s)
Manage Videos
Protect Videos
Topic(s)
Geo Restriction
Player/Video Availability
API(s)
CMS API

In this topic, you will learn how to manage geo-restriction properties for videos using the CMS API. Brightcove's CMS API allows you to add geo-filtering properties to videos to provide a list of countries they can (or cannot) be viewed in.

Introduction

Geo-filtering properties can be added when you initially create the video using a POST request or using a PATCH request to update the video metadata. See Update Videos Using CMS API for an example of an update request.

Access to geo-filtering

Authorization

The operations you will need permissions for in order to update video metadata are video-cloud/video/update or video-cloud/video/all.

Syntax

geo is an object with three properties:

Property Type Required Comments
geo.countries Array of country code Strings no An ISO 3166 list of 2-letter codes in lower-case for countries that will be whitelisted or blacklisted for viewing the video
geo.exclude_countries Boolean no If true, viewing is not allowed in countries included in the geo.countries list; if false, viewing is only allowed in those countries.
geo.restricted Boolean no If true geo-filtering is enabled for video

Request

https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_ID}

Request body:

The request body will be a JSON object containing an array of country abbreviations to be included or excluded:

{"geo" : {
    "restricted" : true,
    "exclude_countries" : false,
    "countries" : ["ph","in","my","ja"]
  }
}