support Contact Support | system status System Status

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.


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

Page last updated on 16 Mar 2020