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

Right

Movida’s rights represent the time window in which a content can be displayed. They apply on a feature or a series and they might be part of a deal or not.

This is how a right looks like:

<right>
  <id type="integer">4</id>
  <external-id>RR12-4</external-id>
  <right-type>archive</right-type>
  <starts type="date">2010-10-10</starts>
  <ends type="date">2011-10-10</ends>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,7-9</episode-selection>
  <clearances-included type="boolean">true</clearances-included>
  <utility-limit type="integer">3</utility-limit>
  <repeats type="boolean">false</repeats>
  <minimum-exploitation type="integer">10</minimum-exploitation>
  <maximum-exploitation type="integer">30</maximum-exploitation>
  <rerun-limit type="integer">5</rerun-limit>
  <parity>start+end</parity>
  <link rel="self" href="https://movida.bebanjo.net/rights/4"/>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/4/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/4/specific_platforms"/>
</right>

This is how an Catchup Right looks through the API:

<right>
  <id type="integer">5</id>
  <external-id>RR12-5</external-id>
  <right-type>catchup</right-type>
  <start-offset-value>1</start-offset-value>
  <start-offset-unit>hours</start-offset-unit>
  <start-offset-reference>after_tx_ends</start-offset-reference>
  <end-offset-value>30</start-offset-value>
  <end-offset-unit>days</start-offset-unit>
  <end-offset-reference>after_tx_ends</start-offset-reference>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,7-9</episode-selection>
  <clearances-included type="boolean">true</clearances-included>
  <utility-limit type="integer">3</utility-limit>
  <repeats type="boolean">false</repeats>
  <minimum-exploitation type="integer">10</minimum-exploitation>
  <maximum-exploitation type="integer">30</maximum-exploitation>
  <rerun-limit type="integer">5</rerun-limit>
  <parity>start+end</parity>
  <link rel="self" href="https://movida.bebanjo.net/rights/4"/>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/4/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/4/specific_platforms"/>
  <link href="https://movida.bebanjo.net/linear_channels/2" rel="reference_tx_channel"/>
</right>

Valid attributes

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

  • external-id (optional): Identifier of the right in the external system.

  • right-type (required): Type of the right. Possible values are “archive” and “catchup”.

  • starts (required): Timestamp representing when the right starts.

  • ends (required): Timestamp representing when the right ends.

  • start-offset-value (optional): For catchup rights, one of the attributes to define when the right starts. Allowed values are positive integers. If specified you need to provide <start-offset-unit> and <start-offset-reference> to define the start completely.

  • start-offset-unit (optional): For catchup rights, one of the attributes to define when the right starts. Allowed values are: minutes, hours, days, weeks, months, years. If specified you need to provide <start-offset-value> and <start-offset-reference> to define the start completely.

  • start-offset-reference (optional): For catchup rights, one of the attributes to define when the right starts. Allowed values are: before_tx_starts, after_tx_starts, after_tx_ends and after_date. If specified you need to provide <start-offset-value> and <start-offset-reference> to define the start completely.

  • reference-start-date (optional): For catchup rights, one of the attributes to define when the right starts. If the <start-offset-reference> is after_date you must need to provide a value (of type date) for this attribute.

  • end-offset-value (optional): For catchup rights, one of the attributes to define when the right ends. Allowed values are positive integers. If specified you need to provide <end-offset-unit> and <end-offset-reference> to define the end completely.

  • end-offset-unit (optional): For catchup rights, one of the attributes to define when the right ends. Allowed values are: minutes, hours, days, weeks, months, years. If specified you need to provide <end-offset-value> and <end-offset-reference> to define the end completely.

  • end-offset-reference (optional): For catchup rights, one of the attributes to define when the right ends. Allowed values are: after_start, after_tx_ends and after_last_episode. If specified you need to provide <end-offset-value> and <end-offset-unit> to define the end completely.

  • reference-tx-nth (optional): For catchup rights, one of the attributes to define when the right ends. Allowed values are: 1 2 3 4 5 6 7 8 9 10 11 12 and all.

  • episode-selection-type (optional): This attribute only makes sense for rights defined on series. Can take three different values:

    • all: The right applies to all episodes in the series.

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

    • except: The right 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

  • clearances-included (optional): If not specified at creation it will default to true.

  • utility-limit (optional): indicates the maximum number of episodes on a series that can be available to any one time. So this attribute can only be set on rights applied to series. Allowed values are: nil (if theres is no such restriction) and positive integers greater than 0.

  • repeats (optional): if not specified at creation it will defaut to false. Indicates if an episode cannot be repeated until all episodes in the series have been scheduled. So this attribute can only be set on rights applied to series. Allowed values are: true or false.

  • minimum-exploitation (optional): indicates the minimum duration in days on exploitation. Allowed values are: nil (if there is no such limit) and integer values greater or equal than 0. If a value maximum_explotation is provided too must be lower than that.

  • maximum-exploitation (optional): indicates the maximum duration in days on exploitation. Allowed values are: nil (if there is no such limit) and integer values greater or equal than 0. If a value minimum_explotation is provided too must be higher than that.

  • rerun-limit (optional): indicates the max allowed number of schedule entries in the same platform and within the availability window. Allowed values are: nil (if there is no such limit) and integer values greater or equal than 1.

  • parity (optional): indicates if schedule entries must be specified en every platform with the same: start date, end date or same start and end dates. Allowed values are: nil (if there is no such restriction), ‘start’, ‘end’, and ‘start+end’

Get a list of all rights in the current account

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

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

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

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/rights
<?xml version="1.0" encoding="UTF-8"?>
<rights>
  <total-entries>113</total-entries>
  <link rel="next" href="https://movida.bebanjo.net/api/rights?page=1"/>
  <link rel="prev" href="https://movida.bebanjo.net/api/rights?page=3"/>
  <right>
    <id type="integer">5</id>
    <external-id>RR12-5</external-id>
    <right-type>catchup</right-type>
    <!-- ... -->
  </right>
  <right>
    <id type="integer">6</id>
    <external-id>RR11-5</external-id>
    <right-type>archive</right-type>
    <!-- ... -->
  </right>
  <!-- ... -->
<rights>

Note: This is a paginated resource. By default, only 50 Rights 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 Rights returned using the following parameters:

  • external_id: It will return only the Right 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 rights from a deal

Given an existing deal, for example:

<deal>
  <id type="integer">2</id>
  <name>Marvel Deal 2013</name>
  <external-id>Marvel2013</external-id>
  <right-type>archive</right-type>
  <minimum-exploitation nil="true"/>
  <maximum-exploitation nil="true"/>
  <rerun-limit nil="true"/>
  <parity nil="true"/>
  <link rel="self" href="https://movida.bebanjo.net/deals/2"/>
  <link rel="rights" href="https://movida.bebanjo.net/deals/2/rights"/>
</deal>

All the rights of that deal can be obtained by following the link rel="rights":

$ curl --digest -u robot_user https://movida.bebanjo.net/api/deals/2/rights
<rights type="array">
  <right>
    <id type="integer">4</id>
    <external-id>RR12-4</external-id>
    <right-type>archive</right-type>
    <starts type="date">2010-10-10</starts>
    <ends type="date">2011-10-10</ends>
    <episode-selection-type>all</episode-selection-type>
    <clearances-included type="boolean">true</clearances-included>
    <utility-limit nil="true"/>
    <repeats type="boolean">false</repeats>
    <minimum-exploitation nil="true"/>
    <maximum-exploitation nil="true"/>
    <rerun-limit nil="true"/>
    <parity nil="true"/>
    <link rel="self" href="https://movida.bebanjo.net/rights/4"/>
    <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
    <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
    <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/4/granted_requirements"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/4/specific_platforms"/>
  </right>
  <right>
    <id type="integer">5</id>
    <right-type>archive</right-type>
    <starts type="date">2011-11-10</starts>
    <ends type="date">2012-10-10</ends>
    <episode-selection-type>only</episode-selection-type>
    <episode-selection>1-5,7,9</episode-selection>
    <clearances-included type="boolean">true</clearances-included>
    <utility-limit nil="true"/>
    <repeats type="boolean">false</repeats>
    <minimum-exploitation nil="true"/>
    <maximum-exploitation nil="true"/>
    <rerun-limit nil="true"/>
    <parity nil="true"/>
    <link rel="self" href="https://movida.bebanjo.net/rights/5"/>
    <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
    <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
    <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/5/granted_requirements"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/5/specific_platforms"/>
  </right>
  <right>
    <id type="integer">6</id>
    <external-id>RR12-5</external-id>
    <right-type>archive</right-type>
    <starts type="date">2013-01-10</starts>
    <ends type="date">2015-01-00T00:00</ends>
    <clearances-included type="boolean">true</clearances-included>
    <minimum-exploitation nil="true"/>
    <maximum-exploitation nil="true"/>
    <rerun-limit nil="true"/>
    <parity nil="true"/>
    <link rel="self" href="https://movida.bebanjo.net/rights/6"/>
    <link rel="licensable" href="http://movida.bebanjo.net/titles/3"/>
    <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
    <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/6/granted_requirements"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/6/specific_platforms"/>
  </right>
</rights>

Get a list of rights from a feature or series

Given an existing feature, for example:

  <title>
    <id type="integer">12</id>
    <name>Silicon Computers</name>
    <title>Silicon Computers</title>
    <external-id nil="true"/>
    <title-type>feature</title-type>
    <tags></tags>
    <link href="https://staging-movida.bebanjo.net/api/titles/12" rel="self"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/schedule" rel="schedule"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/availability_windows" rel="availability_windows"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/title_groups" rel="title_groups"/>
    <link href="https://staging-movida.bebanjo.net/api/licensors/114" rel="licensor"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/images" rel="images"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/assets" rel="assets"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/metadata" rel="metadata"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/blackouts" rel="blackouts"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/rights" rel="rights"/>
    <link href="https://staging-movida.bebanjo.net/api/titles/12/trailers" rel="trailers"/>
  </title>

All the rights of that deal can be obtained by following the link rel="rights":

$ curl --digest -u robot_user https://movida.bebanjo.net/api/titles/12/rights
<rights type="array">
  <right>
    <id type="integer">7</id>
    <external-id>FR2</external-id>
    <right-type>archive</right-type>
    <starts type="date">2013-10-10</starts>
    <ends type="date">2014-10-10</ends>
    <clearances-included type="boolean">true</clearances-included>
    <minimum-exploitation nil="true"/>
    <maximum-exploitation nil="true"/>
    <rerun-limit nil="true"/>
    <parity nil="true"/>
    <link rel="self" href="https://movida.bebanjo.net/api/rights/7"/>
    <link rel="licensable" href="http://movida.bebanjo.net/api/titles/12"/>
    <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/7/granted_requirements"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/7/specific_platforms"/>
  </right>
  <right>
    <id type="integer">8</id>
    <right-type>archive</right-type>
    <starts type="date">2011-11-10</starts>
    <ends type="date">2012-10-10</ends>
    <clearances-included type="boolean">true</clearances-included>
    <minimum-exploitation nil="true"/>
    <maximum-exploitation nil="true"/>
    <rerun-limit nil="true"/>
    <parity nil="true"/>
    <link rel="self" href="https://movida.bebanjo.net/rights/8"/>
    <link rel="licensable" href="http://movida.bebanjo.net/api/titles/12"/>
    <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/8/granted_requirements"/>
    <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/8/specific_platforms"/>
  </right>
</rights>

Get a single right

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

$ curl --digest -u robot_user https://movida.bebanjo.net/rights/6
<right>
  <id type="integer">6</id>
  <external-id>RR12-5</external-id>
  <right-type>archive</right-type>
  <starts type="date">2013-01-10</starts>
  <ends type="date">2015-01-00T00:00</ends>
  <clearances-included type="boolean">true</clearances-included>
  <minimum-exploitation nil="true"/>
  <maximum-exploitation nil="true"/>
  <rerun-limit nil="true"/>
  <parity nil="true"/>
  <link rel="self" href="https://movida.bebanjo.net/rights/6"/>
  <link rel="licensable" href="http://movida.bebanjo.net/titles/3"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/2"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/6/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/6/specific_platforms"/>
</right>

Creating rights for a deal

To create a right, you just need to POST a proper XML right representation (similar to the ones you get when fetching a deal or a licensable) to the rights URL of a given deal or licensable. As explained above, that URL is in the link node whose rel attribute equals rights.

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

cat right.xml
<right>
  <external-id>RR12-4</external-id>
  <right-type>archive</right-type>
  <starts type="date">2010-10-10</starts>
  <ends type="date">2011-10-10</ends>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
</right>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @right.xml "https://movida.bebanjo.net/api/deals/9/rights"

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

<?xml version="1.0" encoding="UTF-8"?>
<right>
  <id type="integer">13</id>
  <external-id>RR12-4</external-id>
  <right-type>archive</right-type>
  <starts type="date">2010-10-10</starts>
  <ends type="date">2011-10-10</ends>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <clearances-included type="boolean">true</clearances-included>
  <utility-limit nil="true"/>
  <repeats type="boolean">false</repeats>
  <minimum-exploitation nil="true"/>
  <maximum-exploitation nil="true"/>
  <rerun-limit nil="true"/>
  <parity nil="true"/>
  <link rel="self" href="http://movida.bebanjo.net/api/rights/13"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/9"/>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/13/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/13/specific_platforms"/>
</right>

A right for a feature or a series can be created the same way, issuing a POST request to that feature or series rights URL.

To create granted_requirements for a right refer to the granted requirement

Inheriting attributes from the deal

When you create a Right from a Deal you can omit some attributes because those attributes will be inherited from the Deal itself.

In the case of Deal of Archive type you can omit right-type, starts and ends when creating a right. So those attributes will be populate with the values on the Deal.

If you have the following deal:

<deal>
  <id type="integer">123</id>
  <name>Marvel Deal 2013</name>
  <external-id>Marvel2013</external-id>
  <right-type>archive</right-type>
  <starts type="date">2014-10-10</starts>
  <ends type="date">2015-10-31</ends>
  <rights-updated-at type="datetime">2014-10-01T00:00:00Z</rights-updated-at>
  <minimum-exploitation>1</minimum-exploitation>
  <maximum-exploitation>10</maximum-exploitation>
  <rerun-limit nil="true"/>
  <parity>start+end</parity>
  <link href="https://staging-movida.bebanjo.net/api/deals/123" rel="self"/>
  <link href="https://staging-movida.bebanjo.net/api/deals/123/rights" rel="rights"/>
  <link href="https://staging-movida.bebanjo.net/api/deals/123/metadata" rel="metadata"/>
  <link href="https://staging-movida.bebanjo.net/api/licensors/114" rel="licensor"/>
  <link href="https://movida.bebanjo.net/deals/2/granted_requirements" rel="granted_requirements"/>
</deal>

And you create the following right:

cat right.xml
<right>
  <external-id>RR12-5</external-id>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/2"/>
</right>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @right.xml "https://movida.bebanjo.net/api/deals/123/rights"

You’ll get the following right:

<?xml version="1.0" encoding="UTF-8"?>
<right>
  <id type="integer">15</id>
  <external-id>RR12-5</external-id>
  <right-type>archive</right-type>
  <starts type="date">2014-10-10</starts>
  <ends type="date">2015-10-31</ends>
  <episode-selection-type>except</episode-selection-type>
  <episode-selection>1,3</episode-selection>
  <clearances-included type="boolean">true</clearances-included>
  <utility-limit nil="true"/>
  <repeats type="boolean">false</repeats>
  <minimum-exploitation>1</minimum-exploitation>
  <maximum-exploitation>10</maximum-exploitation>
  <rerun-limit nil="true"/>
  <parity>start+end</parity>
  <link rel="self" href="http://movida.bebanjo.net/api/rights/15"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/123"/>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/2"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/15/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/15/specific_platforms"/>
</right>

As you see starts, ends and right-type are inherited from the Deal. Besides the right is created with the same granted_requirements and specific_platforms than the Deal. These resources cannot be modified when the right is linked to a deal.

Updating a right

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

cat right_update.xml
<right>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
</right>
$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @right_update.xml "https://movida.bebanjo.net/api/rights/13"

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

<?xml version="1.0" encoding="UTF-8"?>
<right>
  <id type="integer">13</id>
  <external-id>RR12-4</external-id>
  <right-type>archive</right-type>
  <starts type="date">2010-10-10</starts>
  <ends type="date">2011-10-10</ends>
  <episode-selection-type>only</episode-selection-type>
  <episode-selection>1,2</episode-selection>
  <clearances-included type="boolean">true</clearances-included>
  <utility-limit nil="true"/>
  <repeats type="boolean">false</repeats>
  <minimum-exploitation>1</minimum-exploitation>
  <maximum-exploitation>10</maximum-exploitation>
  <rerun-limit nil="true"/>
  <parity>start+end</parity>
  <link rel="self" href="http://movida.bebanjo.net/api/rights/13"/>
  <link rel="deal" href="http://movida.bebanjo.net/deals/9"/>
  <link rel="licensable" href="http://movida.bebanjo.net/title_groups/1"/>
  <link rel="granted_requirements" href="https://movida.bebanjo.net/rights/13/granted_requirements"/>
  <link rel="specific_platforms" href="https://movida.bebanjo.net/rights/13/specific_platforms"/>
</right>

Deleting a right

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

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

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

Last updated May 05th, 2017.