Using the CMS API: Add Geo-Filtering

Video Cloud
API Developer
Manage Videos
Protect Videos
Geo Restriction
Player/Video Availability

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.


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


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


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 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"]