Developers

How can we help you?

Blackout

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

This is how a Blackout looks like:

<?xml version="1.0" encoding="UTF-8"?>
<blackout>
  <id type="integer">4</id>
  <external-id>ext-id-004</external-id>
  <name>Blackout #1</name>
  <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"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/4/specific_platforms"/>
  <link rel="note" href="https://movida.bebanjo.net/api/blackouts/4/note"/>
</blackout>

{
  "resource_type": "blackout",
  "id": 4,
  "external_id": "ext-id-004",
  "name": "Blackout #1",
  "reason": "Missing rights",
  "from": "2010-10-10",
  "to": "2011-10-10",
  "episode_selection_type": "except",
  "episode_selection": "1,7-9",
  "self_link": "https://movida.bebanjo.net/api/blackouts/4",
  "licensable_link": "https://movida.bebanjo.net/api/title_groups/1",
  "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/4/granted_requirements",
  "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/4/specific_platforms",
  "note_link": "https://movida.bebanjo.net/api/blackouts/4/note"
}

Valid attributes

id (required): Mediagenix On-Demand internal identifier of the blackout.
external-id (optional): An external system identifier of the blackout.
name (optional): name of the blackout, meaningful to the user. When no value is provided, Mediagenix On-Demand will store a generic name based on number of blackouts in the licensable, such as Blackout #1.
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. Can’t be longer than 255 characters. 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>

{
  // ...
  "blackouts_link": "https://movida.bebanjo.net/api/blackouts",
  // ...
}

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

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/blackouts

<?xml version="1.0" encoding="UTF-8"?>
<blackouts type="array">
  <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>

{
  "total_entries": 27,
  "entries": [
    {
      "resource_type": "blackout",
      "id": 5,
      "external_id": "ext-id-005",
      // ...
    },
    {
      "resource_type": "blackout",
      "id": 6,
      "external_id": "ext-id-006",
      // ...
    },
    // ...
  ]
}

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>
  <season-reference-id>Winter</season-reference-id>
  <tags>Action,Drama</tags>
  <link rel="self" href="https://movida.bebanjo.net/api/title_groups/180"/>
  <link rel="titles" href="https://movida.bebanjo.net/api/title_groups/180/titles"/>
  <link rel="schedule" href="https://movida.bebanjo.net/api/title_groups/180/schedule"/>
  <link rel="images" href="https://movida.bebanjo.net/api/title_groups/180/images"/>
  <link rel="metadata" href="https://movida.bebanjo.net/api/title_groups/180/metadata"/>
  <link rel="blackouts" href="https://movida.bebanjo.net/api/title_groups/180/blackouts"/>
  <link rel="rights" href="https://movida.bebanjo.net/api/title_groups/180/rights"/>
  <link rel="denied_rights" href="https://movida.bebanjo.net/api/title_groups/180/denied_rights"/>
  <link rel="rules" href="https://movida.bebanjo.net/api/title_groups/180/rules"/>
  <link rel="clips" href="https://movida.bebanjo.net/api/title_groups/180/clips"/>
  <link rel="note" href="https://movida.bebanjo.net/api/title_groups/180/note"/>
</title-group>

{
  "resource_type": "title_group",
  "id": 180,
  "name": "CSI: Crime Scene Investigation",
  "external_id": "14320",
  "title_group_type": "series",
  "season_number": 1,
  "season_reference_id": "Winter",
  "tags": "Action,Drama",
  "self_link": "https://movida.bebanjo.net/api/title_groups/180",
  "titles_link": "https://movida.bebanjo.net/api/title_groups/180/titles",
  "schedule_link": "https://movida.bebanjo.net/api/title_groups/180/schedule",
  "images_link": "https://movida.bebanjo.net/api/title_groups/180/images",
  "metadata_link": "https://movida.bebanjo.net/api/title_groups/180/metadata",
  "blackouts_link": "https://movida.bebanjo.net/api/title_groups/180/blackouts",
  "rights_link": "https://movida.bebanjo.net/api/title_groups/180/rights",
  "denied_rights_link": "https://movida.bebanjo.net/api/title_groups/180/denied_rights",
  "rules_link": "https://movida.bebanjo.net/api/title_groups/180/rules",
  "clips_link": "https://movida.bebanjo.net/api/title_groups/180/clips",
  "note_link": "https://movida.bebanjo.net/api/title_groups/180/note"
}

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

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

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/title_groups/180/blackouts

<blackouts type="array">
  <blackout>
    <id type="integer">4</id>
    <external-id nil="true"/>
    <name>Blackout #1</name>
    <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"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/4/specific_platforms"/>
  </blackout>
  <blackout>
    <id type="integer">5</id>
    <external-id nil="true"/>
    <name>Blackout #2</name>
    <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"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/5/specific_platforms"/>
  </blackout>
</blackouts>

{
  "entries": [
    {
      "resource_type": "blackout",
      "id": 4,
      "external_id": null,
      "name": "Blackout #1",
      "reason": "Missing rights",
      "from": "2010-10-10",
      "to": "2011-10-10",
      "episode_selection_type": "except",
      "episode_selection": "1,7-9",
      "self_link": "https://movida.bebanjo.net/api/blackouts/4",
      "licensable_link": "https://movida.bebanjo.net/api/title_groups/180",
      "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/4/granted_requirements",
      "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/4/specific_platforms",
      "note_link": "https://movida.bebanjo.net/api/blackouts/4/note"
    },
    {
      "resource_type": "blackout",
      "id": 5,
      "external_id": null,
      "name": "Blackout #2",
      "reason": "Missing rights",
      "from": "2012-10-10",
      "to": "2013-10-10",
      "episode_selection_type": "all",
      "self_link": "https://movida.bebanjo.net/api/blackouts/5",
      "licensable_link": "https://movida.bebanjo.net/api/title_groups/180",
      "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/5/granted_requirements",
      "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/5/specific_platforms",
      "note_link": "https://movida.bebanjo.net/api/blackouts/5/note"
    }
  ]
}

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:password https://movida.bebanjo.net/api/blackouts/5

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/blackouts/5

<blackout>
  <id type="integer">5</id>
  <external-id>sample-external-id-001</external-id>
  <name>Exclusivity deal 001</name>
  <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"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/5/specific_platforms"/>
  <link rel="note" href="https://movida.bebanjo.net/api/blackouts/5/note"/>
</blackout>

{
  "resource_type": "blackout",
  "id": 5,
  "external_id": "sample-external-id-001",
  "name": "Exclusivity deal 001",
  "reason": "Missing rights",
  "from": "2012-10-10",
  "to": "2013-10-10",
  "episode_selection_type": "all",
  "self_link": "https://movida.bebanjo.net/api/blackouts/5",
  "licensable_link": "https://movida.bebanjo.net/api/title_groups/180",
  "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/5/granted_requirements",
  "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/5/specific_platforms",
  "note_link": "https://movida.bebanjo.net/api/blackouts/5/note"
}

Creating a blackout

To create a blackout, you just need to POST a proper XML/JSON 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/JSON 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

$ cat blackout.json

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

{
  "external_id": "the-blackout-id-in-your-system",
  "from": "2010-10-10",
  "to": "2011-10-10",
  "episode_selection_type": "except",
  "episode_selection": "1,3"
}

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

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

Mediagenix On-Demand will return the full XML/JSON of the blackout just created:

<blackout>
  <id type="integer">6</id>
  <external-id>the-blackout-id-in-your-system</external-id>
  <name>Blackout #2</name>
  <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"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/6/specific_platforms"/>
  <link rel="note" href="https://movida.bebanjo.net/api/blackouts/6/note"/>
</blackout>

{
  "resource_type": "blackout",
  "id": 6,
  "external_id": "the-blackout-id-in-your-system",
  "name": "Blackout #2",
  "from": "2010-10-10",
  "to": "2011-10-10",
  "episode_selection_type": "except",
  "episode_selection": "1,3",
  "self_link": "https://movida.bebanjo.net/api/blackouts/6",
  "licensable_link": "https://movida.bebanjo.net/api/title_groups/10113938",
  "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/6/granted_requirements",
  "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/6/specific_platforms",
  "note_link": "https://movida.bebanjo.net/api/blackouts/6/note"
}

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

$ cat blackout_update.json

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

{
  "episode_selection_type": "only",
  "episode_selection": "1,2"
}

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

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

As always Mediagenix On-Demand will return the full XML/JSON 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>
  <name>Blackout #2</name>
  <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"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/api/blackouts/13/specific_platforms"/>
  <link rel="note" href="https://movida.bebanjo.net/api/blackouts/13/note"/>
</blackout>

{
  "resource_type": "blackout",
  "id": 13,
  "external_id": "ext-id-0013",
  "name": "Blackout #2",
  "reason": "Missing rights",
  "from": "2010-10-10",
  "to": "2011-10-10",
  "episode_selection_type": "only",
  "episode_selection": "1,2",
  "self_link": "https://movida.bebanjo.net/api/blackouts/13",
  "licensable_link": "https://movida.bebanjo.net/api/title_groups/180",
  "granted_requirements_link": "https://movida.bebanjo.net/api/blackouts/13/granted_requirements",
  "specific_platforms_link": "https://movida.bebanjo.net/api/blackouts/13/specific_platforms",
  "note_link": "https://movida.bebanjo.net/api/blackouts/13/note"
}

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.

Managing blackout’s specific platforms

In order to apply the blackout to one or many platforms, you’ll need to use the link identified by a rel attribute equals to specific_platforms. See the documentation of the specific_platform 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"

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

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