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

BeBanjo

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="https://movida.bebanjo.net/api/title_groups/1"/>
  <link rel="granted_requirements" href="https://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="https://movida.bebanjo.net/api/title_groups/180"/>
    <link rel="granted_requirements" href="https://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="https://movida.bebanjo.net/api/title_groups/180"/>
    <link rel="granted_requirements" href="https://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="https://movida.bebanjo.net/api/title_groups/180"/>
  <link rel="granted_requirements" href="https://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="https://movida.bebanjo.net/api/blackouts/6"/>
  <link rel="licensable" href="https://movida.bebanjo.net/api/title_groups/1"/>
  <link rel="granted_requirements" href="https://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="https://movida.bebanjo.net/api/title_groups/180"/>
  <link rel="granted_requirements" href="https://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 September 19th, 2017.