Adding Geo-Filtering

In this topic, you will learn how to manage geo-restriction properties for videos using the CMS API. The 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.

Instead of, or in addition to, applying geo-filtering at the video level, you can apply geo-filtering to Brightcove players via policy keys. Video Cloud looks at both video and player level geo-filtering policies, and will apply both. If a country is excluded by either policy, the video will not be available in country.

Note that country codes should be entered lower-case.

Some publishers have requested the ability to geo filter videos to US military bases as well as the US. To support this, there is a US Military option. While there is no 100% reliable way to identify a military base, when an IP that resolves to a .mil domain is encountered, and is not in the US, it will be identified as coming from a US military base rather than its actual country of origin. .mil addresses that are in the US will still be identified as "us".

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

To update a video, send a PATCH request to:

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