We use cookies (just for analytics) on this website. If you continue we will assume you are happy with it. ok

BeBanjo

Menu

Back to index

Movida / Metadata API

Back to index

Blackout

Blackouts represent the time window in which a content can’t be displayed. They apply on a feature or a series.

This is how a Blackout looks like:

<blackout>
  <id type="integer">4</id>
  <external-id>ext-id-004</external-id>
  <reason>Missing rights</reason>
  <from type="date">2010-10-10</from>
  <to type="date">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,7-9</episode-selection>
  <link rel="self" href="https://movida.bebanjo.net/api/blackouts/4"/>
  <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/1"/>
  <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/4/granted_requirements"/>
</blackout>

Valid attributes

  • id (required): Movida internal identifier of the blackout.

  • external-id (optional): An external system identifier of the blackout.

  • from (required): a date timestamp representing when the blackout starts.

  • to (required): a date timestamp representing when the blackout ends.

  • episode-selection-type (optional): this attribute only makes sense for blackouts defined on series. It can take three different values:

    • all: the blackout applies to all episodes in the series.

    • only: the blackout applies to the episode specified in the attribute <episode-selection>.

    • except: the blackout applies to all episodes except those specified in the attribute <episode-selection>.

  • episode-selection (optional): this attribute only makes sense when <episode-selection-type> has the values only or except. Its purpose is to specify a range of episodes, separating the episode numbers by commas or by a dash. A dash range means that all the episodes in that range are included. For example:

    • 1,3-5,7,9 range includes the episodes 1, 3, 4, 5, 7 and 9.

    • 1-3,9,11-13 range includes the episodes 1, 2, 3, 9, 11, 12 and 13.

Get a list of all blackouts in the current account

Blackouts are linked from the root of the API, through the link identified with the rel="blackouts" attribute:

<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <!-- ... -->
  <link rel="blackouts" href="https://movida.bebanjo.net/api/blackouts">
</movida>

Following that link, we can fetch the list of blackouts in the current account.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/blackouts

<?xml version="1.0" encoding="UTF-8"?>
<blackouts>
  <total-entries>27</total-entries>
  <blackout>
    <id type="integer">5</id>
    <external-id>ext-id-005</external-id>
    <!-- ... -->
  </blackout>
  <blackout>
    <id type="integer">6</id>
    <external-id>ext-id-006</external-id>
    <!-- ... -->
  </blackout>
  <!-- ... -->
<blackouts>

Note: This is a paginated resource. By default, only 50 blackouts will be included in each page but you can override this default by using the per_page parameter described in the next section. The total-entries attribute will indicate the total number of entries and the links rel="next" and rel="prev" should be used to get the next and the previous pages.

Valid attributes

You can filter the list of blackouts returned using the following parameters:

  • external_id: It will return only the blackout with the exact given external-id (if any).

  • per_page: Number of elements returned in each page. The maximum value allowed is 200 and the default is 50.

  • page: Number of the page you want to be returned.

Get a list of blackouts from a licensable

We’ll be fetching the blackouts from a series, but this is also applicable for titles.

Given an existing Series, for example:

<title-group>
  <id type='integer'>180</id>
  <name>CSI: Crime Scene Investigation</name>
  <external-id>14320</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <link href="https://movida.bebanjo.net/api/title_groups/180/titles" rel="titles"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/180/schedule" rel="schedule"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/180/metadata" rel="metadata"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/180/images" rel="images"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/180/blackouts" rel="blackouts"></link>
</title-group>

All the blackouts of that title group can be obtained by following the link rel="blackouts":

$ curl --digest -u robot_user https://movida.bebanjo.net/api/title_groups/180/blackouts

<blackouts type="array">
  <blackout>
    <id type="integer">4</id>
    <reason>Missing rights</reason>
    <from type="date">2010-10-10</from>
    <to type="date">2011-10-10</to>
    <episode-selection-type>except</episode-selection-type>
    <episode-selection>1,7-9</episode-selection>
    <link rel="self" href="https://movida.bebanjo.net/api/blackouts/4"/>
    <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/180"/>
    <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/4/granted_requirements"/>
  </blackout>
  <blackout>
    <id type="integer">5</id>
    <reason>Missing rights</reason>
    <from type="date">2012-10-10</from>
    <to type="date">2013-10-10</to>
    <episode-selection-type>all</episode-selection-type>
    <link rel="self" href="https://movida.bebanjo.net/api/blackouts/5"/>
    <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/180"/>
    <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/5/granted_requirements"/>
  </blackout>
</blackouts>

Get a single blackout

Just do a GET to the URI of the Blackout (the one in the attribute rel="self"):

$ curl --digest -u robot_user https://movida.bebanjo.net/api/blackouts/5

<blackout>
  <id type="integer">5</id>
  <external-id>sample-external-id-001</external-id>
  <reason>Missing rights</reason>
  <from type="date">2012-10-10</from>
  <to type="date">2013-10-10</to>
  <episode-selection-type>all</episode-selection-type>
  <link rel="self" href="https://movida.bebanjo.net/api/blackouts/5"/>
  <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/180"/>
  <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/5/granted_requirements"/>
</blackout>

Creating a blackout

To create a blackout, you just need to POST a proper XML blackout representation to the blackouts URL of a given title group or title. As explained above, that URL is in the link node whose ‘rel’ attribute equals ‘blackouts’.

For example, the following XML issued as a POST to the blackouts URL of a title would create a blackout (we’ll use $ curl’s @ option, which reads data to be posted from a file):

cat blackout.xml

<blackout>
  <external-id>the-blackout-id-in-your-system</external-id>
  <from type="date">2010-10-10</from>
  <to type="date">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
</blackout>

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @blackout.xml "https://movida.bebanjo.net/api/title_groups/1/blackouts"

Movida will return the full XML of the blackout just created:

<blackout>
  <id type="integer">6</id>
  <external-id>the-blackout-id-in-your-system</external-id>
  <from type="date">2010-10-10</from>
  <to type="date">2011-10-10</to>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <link rel="self" href="http://movida.bebanjo.net/api/blackouts/6"/>
  <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/1"/>
  <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/6/granted_requirements"/>
</blackout>

Updating blackouts

As our introduction to REST APIs guide suggests, you can update a blackout issuing a PUT request to each blackout URI:

cat blackout_update.xml

<blackout>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
</blackout>

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @blackout_update.xml "https://movida.bebanjo.net/api/blackouts/13"

As always Movida will return the full XML of the blackout just updated:

<?xml version="1.0" encoding="UTF-8"?>
<blackout>
  <id type="integer">13</id>
  <external-id>ext-id-0013</external-id>
  <reason>Missing rights</reason>
  <from type="date">2012-10-10</from>
  <to type="date">2013-10-10</to>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
  <link rel="self" href="https://movida.bebanjo.net/api/blackouts/13"/>
  <link rel="licensable" href="http://movida.bebanjo.net/api/title_groups/180"/>
  <link rel="granted_requirements" href="http://movida.bebanjo.net/api/blackouts/13/granted_requirements"/>
</blackout>

Managing blackout’s granted requirements

In order to apply the blackout to one or many requirements, you’ll need to use the link identified by a rel attribute equals to granted_requirements. See the documentation of the granted requirement resource for additional information.

Deleting blackouts

Also you can delete a blackout using DELETE request to each blackout URI:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/blackouts/33"

The DELETE request doesn’t return anything, as that blackout is now gone.

Last updated May 05th, 2017.