Add 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".

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