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.


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.


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



To update a video, send a PATCH request to:

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