Geo-filtering with the Media API

You can use Brightcove's geo-filtering feature to restrict access to content based on the viewer's geographic location. For example, if you have a video that, for legal reasons, cannot be distributed outside the U.S. and Canada, you can set geo-filtering on the video to keep viewers outside of the approved countries from accessing that content. You can also use geo-filtering to restrict access to players. Filtering is supported for over 240 countries and regions defined by ISO-3166.

The ability to use geo-filtering to restrict videos is a feature available to Brightcove Pro or Enterprise publishers for an additional fee. Contact Brightcove if you want to upgrade your account to include Quova geo-filtering.

Geo-filtering can be either exclusive or inclusive of the list of countries you select. This means that you can specify countries that should have access to the content in question (inclusive). Alternatively, you can specify countries that should not have access to the content in question (exclusive). This topic describes how to use the Media API to set geo-filtering properties for your videos.

Geo-filtering properties for videos

Geo-filtering for videos is controlled by three optional properties of the Video object:

Setting geo-filtering with Media API Write methods

You set the geo-filtering properties for a video using the create_video or update_video methods. For example, the JSON to specify that a video can be viewed only in Malta (mt) could look like this:

{"method": "create_video",
 "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
            "video" : {"id":38,"name":"The Maltese Falcon",
                       "shortDescription":"The stuff dreams are made of.",
                       "geoRestricted":true,"geoFilterExclude":false,
                       "geoFilteredCountries":["mt"]},
            "filename":"malteseFalcon.mp4",}
}

You might update the video to specify that it can be viewed everywhere except the listed countries with JSON like this:

{"method": "update_video",
 "params": {"token" : "riBfgveLvpRb-rHGiBBouSAXs-Q8NmphGxt0z04kE.",
            "video" : {"id":38,"name":"The Maltese Falcon",
                       "shortDescription":"The stuff dreams are made of.",
                       "geoRestricted":true,"geoFilterExclude":true,
                       "geoFilteredCountries":["mt","cy","es","gr"]},
           }
}

Error messages for geo-filtering

You might get one of the following error codes in response to a function call that includes geo-filtering properties: