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

Title group

A title group is exactly that, a group of titles. Currently in Movida there are two types: Series and Collections

Series

Note: This resource links can be expanded using the expand option except the blackouts and rights links.

This is generally a season, and a title can only belong to one series. A title that belongs to a series is an episode. An example would be “Season 1 of CSI: Crime Scene Investigation”. A specific episode (say, where Grissom, through a long shot extrapolation discovers who the killer was), can only belong to one season at a time. Hmmm… Ok, bad example.

It looks like this (notice the title-group-type):

<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>
  <tags>Drama,Action</tags>
  <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>

Collections

Note: This resource links can be expanded using the expand option except the blackouts and rights links.

A collection is a group of titles of any type (episodes, features, ads, promos…). A title can belong or not to one or many collections. Like this, Movida enables its users to package titles of different series together so that they can be scheduled on VoD. An example would be “CSI: Trilogy”, an special that contains three episodes, one from each strand (Vegas, Miami and New York). Those episodes belong to their specific series, but they can be packaged in various ways.

It looks like this:

<title-group>
  <id type='integer'>215</id>
  <name>CSI: Trilogies</name>
  <external-id></external-id>
  <title-group-type>title_group</title-group-type>
  <tags>Drama,Action</tags>
  <link href="https://movida.bebanjo.net/api/title_groups/215/titles" rel="titles"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/215/schedule" rel="schedule"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/215/metadata" rel="metadata"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/215/images" rel="images"></link>
</title-group>

Title group attributes

  • id (required): Movida internal identifier of the title group. It shouldn’t be provided in the creation of the resource, because Movida will assign that value.
  • name (required): the name of the title group.
  • external-id (optional): the identifier of the title group in the external system. If provided, it has to be unique in the scope of the company.
  • title-group-type (required): the type of title group. Possible values are “series” (for series) and “title_group” (for collections).
  • season-number (optional): the season number as described above; only visible if the title-group-type is “series” and the season number in series feature is enabled for the company.
  • tags (optional): the tags as a list separated by commas of the title group.

Accessing title groups

Title groups can be accessed always by navigating the corresponding nodes.

Get a list of all title groups

To return a list of all title groups in your account (this can be a bit massive - note that at the moment there is no paging available), it would go like this:

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

And would yield something like:

<?xml version='1.0' encoding='utf-8' ?>
<title-groups type='array'>
  <title-group>
    <id type='integer'>1</id>
    <name>Sunrise</name>
    <external-id>23450</external-id>
    <title-group-type>series</title-group-type>
    <season-number>1</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.bebanjo.net/api/title_groups/1/titles" rel="titles"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/1/schedule" rel="schedule"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/1/metadata" rel="metadata"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/1/images" rel="images"></link>
  </title-group>
  <title-group>
    <id type='integer'>2</id>
    <name>Peppa Pig: S02</name>
    <external-id>11512</external-id>
    <title-group-type>series</title-group-type>
    <season-number>2</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.bebanjo.net/api/title_groups/2/titles" rel="titles"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/schedule" rel="schedule"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/metadata" rel="metadata"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/images" rel="images"></link>
  </title-group>
</title-groups>

Valid attributes

  • external_id: You can filter the list of title groups by passing in an external_id. Because Movida was designed to integrate with external content management systems, it has an attribute called external_id for every series and every title. This attribute can be used to store the ID of that specific item in an external system.

If you needed to access a title_group by external_id, you can do so by passing the parameter external_id to the list of title_groups, like this:

$ curl --digest -u robot_user https://movida.bebanjo.net/api/title_groups?external_id=11523

Which would filter by the passed external_id like:

<?xml version='1.0' encoding='utf-8' ?>
<title-groups type='array'>
  <title-group>
    <id type='integer'>2</id>
    <name>Peppa Pig: S02</name>
    <external-id>11512</external-id>
    <title-group-type>series</title-group-type>
    <season-number>2</season-number>
    <tags>Drama,Action</tags>
    <link href="https://movida.bebanjo.net/api/title_groups/2/titles" rel="titles"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/schedule" rel="schedule"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/metadata" rel="metadata"></link>
    <link href="https://movida.bebanjo.net/api/title_groups/2/images" rel="images"></link>
  </title-group>
</title_groups>

Get a specific title group

This is a good way to recover information about a specific title_group. We recommend that you use its full URL as the ID that you store in your systems, if you ever need to re-access it. Following the previous example:

$ curl --digest -u robot_user https://movida.bebanjo.net/api/title_groups/2
<?xml version='1.0' encoding='utf-8' ?>
<title-group>
  <id type='integer'>2</id>
  <name>Peppa Pig: S02</name>
  <external-id>11512</external-id>
  <title-group-type>series</title-group-type>
  <season-number>2</season-number>
  <tags>Drama,Action</tags>
  <link href="https://movida.bebanjo.net/api/title_groups/2/titles" rel="titles"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/schedule" rel="schedule"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/metadata" rel="metadata"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/images" rel="images"></link>
</title-group>

Remember you can use the expand me some nodes trick if you want to, for instance, find out what is the schedule of a particular title_group.

$ curl --digest -u robot_user https://movida.bebanjo.net/api/title_groups/2?expand=schedule,schedulings

This would expand the rel="schedule" link, and then would also expand the rel="schedulings" link inside the schedule, yielding something like:

<?xml version='1.0' encoding='utf-8' ?>
<title-group>
  <id type='integer'>2</id>
  <name>Peppa Pig: S02</name>
  <external-id>11523</external-id>
  <title-group-type>series</title-group-type>
  <season-number>2</season-number>
  <tags>Drama,Action</tags>
  <link href="https://movida.bebanjo.net/api/title_groups/2/titles" rel="titles"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/metadata" rel="metadata"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/images" rel="images"></link>
  <link href="https://movida.bebanjo.net/api/title_groups/2/schedule" rel="schedule">
    <link href="https://movida.bebanjo.net/api/title_groups/2/schedule/schedulings" rel="schedulings">
      <schedulings type='array'>
        <scheduling>
          <id type='integer'>40</id>
          <put-up type='datetime'>2010-03-31T22:00:00Z</put-up>
          <take-down type='datetime'>2010-06-01T21:59:59Z</take-down>
          <scheduling-type>archive</scheduling-type>
          <tags>Drama,Action</tags>
          <link href="https://movida.bebanjo.net/api/title_groups/2" rel="title_group"></link>
          <link href="https://movida.bebanjo.net/api/titles/581" rel="title"></link>
        </scheduling>
      </schedulings>
    </link>
  </link>
</title-group>

Get a list of all titles on a title group

To return of all titles for a title group, it would go like this (please note that at the moment, pagination is not default):

$ curl --digest -u robot_user http://movida.bebanjo.net/api/title_groups/41/titles?pagination=true

And would yield something like:

<?xml version='1.0' encoding='utf-8' ?>
<titles type='array'>
  <total-entries>2</total-entries>
  <link rel="next" href="http://movida.bebanjo.net/api/title_groups/41/titles?pagination=true&page=2"/>
  <title>
    <id type="integer">73</id>
    <title>E01, Episode 1</title>
    <name>Episode 1</name>
    <episode-number type="integer">1</episode-number>
    <external-id>C5147630001</external-id>
    <title-type>episode</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.bebanjo.net/api/titles/73" rel="self"/>
    <link href="http://movida.bebanjo.net/api/titles/73/schedule" rel="schedule"/>
    <link href="http://movida.bebanjo.net/api/titles/73/availability_windows" rel="availability_windows"/>
    <link href="http://movida.bebanjo.net/api/title_groups/41" rel="series"/>
    <link href="http://movida.bebanjo.net/api/titles/73/images" rel="images"/>
    <link href="http://movida.bebanjo.net/api/titles/73/metadata" rel="metadata"/>
  </title>
  <title>
    <id type="integer">74</id>
    <title>E02, Episode 2</title>
    <name>Episode 2</name>
    <episode-number type="integer">1</episode-number>
    <external-id>C5147630002</external-id>
    <title-type>episode</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.bebanjo.net/api/titles/74" rel="self"/>
    <link href="http://movida.bebanjo.net/api/titles/74/schedule" rel="schedule"/>
    <link href="http://movida.bebanjo.net/api/titles/74/availability_windows" rel="availability_windows"/>
    <link href="http://movida.bebanjo.net/api/title_groups/41" rel="series"/>
    <link href="http://movida.bebanjo.net/api/titles/74/images" rel="images"/>
    <link href="http://movida.bebanjo.net/api/titles/74/metadata" rel="metadata"/>
  </title>
</titles>

Note: With enabled pagination, only 50 titles will be included in each page by default. But you can override this default by using the per_page parameter. 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 so you can navigate for all the titles for a title group.

Valid attributes

  • pagination: Note that by default, this is not paginated endpoint. If you want to enable pagination you need to provide the pagination parameter with a value of “true”.

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

  • page: Number of the page you want to be returner. Only effective with enabled pagination.

Note: This is a paginated endpoint for the Title resource. By default, only 50 Titles will be included in each page but you can override this default by using the per_page parameter. 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 so you can navigate for all the Titles for a title group.

Creating title groups

Creating new title groups is easy, you just have to post a title group resource (like the ones you get when retrieving title groups) to the URL of a link whose rel is title_groups, like the one you’ll find in the API root:

$ curl -u robot:yourpassword --digest "http://localhost:3000/api"
<?xml version="1.0" encoding="UTF-8"?>
<movida>
  <link rel="titles" href="http://localhost:3000/api/titles"/>
  <link rel="platforms" href="http://localhost:3000/api/platforms"/>
  <link rel="title_groups" href="http://localhost:3000/api/title_groups"/>
  <link rel="schedule" href="http://localhost:3000/api/schedule"/>
  <!-- ... -->
</movida>

The only required field is the name of the title group, all the rest of the fields are optional (but remember that title-group-type defaults to title_group).

So we can create a new empty title group just like this (we’ll be using curl’s @ option, which reads data to be posted from a file):

$ cat title_group.xml
<title-group>
  <name>The Best War Movies</name>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title_group.xml "http://movida.bebanjo.net/api/title_groups"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">4</id>
  <name>The Best War Movies</name>
  <external-id nil="true"></external-id>
  <title-group-type>title_group</title-group-type>
  <tags></tags>
  <link rel="titles" href="http://movida.bebanjo.net/api/title_groups/4/titles"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/title_groups/4/schedule"/>
  <link rel="self" href="http://movida.bebanjo.net/api/title_groups/4"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/title_groups/4/metadata"/>
  <link rel="images" href="https://movida.bebanjo.net/api/title_groups/4/images"/>
</title-group>

In the case of a series, we just need to add the proper type:

$ cat series.xml
<title-group>
  <name>IT Crowd</name>
  <title-group-type>series</title-group-type>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @series.xml "http://movida.bebanjo.net/api/title_groups"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">6</id>
  <name>IT Crowd</name>
  <external-id nil="true"></external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.bebanjo.net/api/title_groups/6/titles"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/title_groups/6/schedule"/>
  <link rel="self" href="http://movida.bebanjo.net/api/title_groups/6"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/title_groups/6/metadata"/>
  <link rel="images" href="http://movida.bebanjo.net/api/title_groups/6/images"/>
</title-group>

Creating series with episodes

In the case of a series, you can include the episodes and create them all together with the series. It can be done in a similar fashion to expanding the titles link when fetching a series:

$ cat series.xml
<title-group>
  <name>IT Crowd</name>
  <title-group-type>series</title-group-type>
  <external-id>12300000</external-id>
  <season-number>1</season-number>
  <link rel="titles">
    <titles type="array">
      <title>
        <name>Episode 1</name>
        <episode-number>1</episode-number>
        <external-id>12300001</external-id>
        <title-type>episode</title-type>
      </title>
      <title>
        <name>Episode 2</name>
        <episode-number>2</episode-number>
        <external-id>12300002</external-id>
        <title-type>episode</title-type>
      </title>
      <title>
        <name>Episode 3</name>
        <episode-number>3</episode-number>
        <external-id>12300003</external-id>
        <title-type>episode</title-type>
      </title>
    </titles>
  </link>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @series.xml "http://movida.bebanjo.net/api/title_groups?expand=titles"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.bebanjo.net/api/title_groups/9/titles">
    <titles type="array">
      <title>
        <id type="integer">13</id>
        <title>E01, Episode 1</title>
        <name>Episode 1</name>
        <episode-number type="integer">1</episode-number>
        <external-id>12300001</external-id>
        <title-type>episode</title-type>
        <tags></tags>
        <link rel="schedule" href="http://movida.bebanjo.net/api/titles/13/schedule"/>
        <link rel="series" href="http://movida.bebanjo.net/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/3"/>
        <link rel="self" href="http://movida.bebanjo.net/api/titles/13"/>
        <link rel="images" href="http://movida.bebanjo.net/api/titles/13/images"/>
        <link rel="metadata" href="http://movida.bebanjo.net/api/titles/13/metadata"/>
      </title>
      <title>
        <id type="integer">14</id>
        <title>E02, Episode 2</title>
        <name>Episode 2</name>
        <episode-number type="integer">2</episode-number>
        <external-id>12300002</external-id>
        <tags></tags>
        <link rel="schedule" href="http://movida.bebanjo.net/api/titles/14/schedule"/>
        <link rel="series" href="http://movida.bebanjo.net/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/3"/>
        <link rel="self" href="http://movida.bebanjo.net/api/titles/14"/>
        <link rel="images" href="http://movida.bebanjo.net/api/titles/14/images"/>
        <link rel="metadata" href="http://movida.bebanjo.net/api/titles/14/metadata"/>
      </title>
      <title>
        <id type="integer">15</id>
        <title>E03, Episode 3</title>
        <name>Episode 3</name>
        <episode-number type="integer">3</episode-number>
        <external-id>12300003</external-id>
        <title-type>episode</title-type>
        <tags></tags>
        <link rel="schedule" href="http://movida.bebanjo.net/api/titles/15/schedule"/>
        <link rel="series" href="http://movida.bebanjo.net/api/title_groups/9"/>
        <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/3"/>
        <link rel="self" href="http://movida.bebanjo.net/api/titles/15"/>
        <link rel="images" href="http://movida.bebanjo.net/api/titles/15/images"/>
        <link rel="metadata" href="http://movida.bebanjo.net/api/titles/15/metadata"/>
      </title>
    </titles>
  </link>
  <link rel="schedule" href="http://movida.bebanjo.net/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.bebanjo.net/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.bebanjo.net/api/title_groups/9/images"/>
</title-group>

Updating and deleting title groups

As our introduction to REST APIs page suggests, you can update and delete title groups issuing PUT and DELETE requests to each title groups URL:

$ cat series.xml
<title-group>
  <name>IT Crowd Season 1</name>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X PUT -d @series.xml "http://movida.bebanjo.net/api/title_groups/9"
<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd Season 1</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="titles" href="http://movida.bebanjo.net/api/title_groups/9/titles"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.bebanjo.net/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.bebanjo.net/api/title_groups/9/images"/>
</title-group>
$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X DELETE "http://movida.bebanjo.net/api/title_groups/9"

If the type of the title group removed is series, then associated episodes will also be removed.

Series and brands

Series (i.e. Title Groups where title_group_type="series") can optionally belong to a brand. This is how a series belonging to a brand will look like in the API:

<?xml version="1.0" encoding="UTF-8"?>
<title-group>
  <id type="integer">9</id>
  <name>IT Crowd Season 1</name>
  <external-id>12300000</external-id>
  <title-group-type>series</title-group-type>
  <season-number>1</season-number>
  <tags></tags>
  <link rel="brand" href="http://movida.bebanjo.net/api/brands/123"/>
  <link rel="titles" href="http://movida.bebanjo.net/api/title_groups/9/titles"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/title_groups/9/schedule"/>
  <link rel="self" href="http://movida.bebanjo.net/api/title_groups/9"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/title_groups/9/metadata"/>
  <link rel="images" href="http://movida.bebanjo.net/api/title_groups/9/images"/>
</title-group>

Note: The additional link rel="brand" only present when the Title Group is a Series belonging to a Brand. You can make a Series belong to a Brand using the API just by including the link rel="brand" pointing to an existing Brand when you create or update the Title Group as described earlier in this page. Alternatively, if you create the Title Group by POSTing the XML representation of a Series to the link rel="series" of an existing Brand, then the new Series created will belong to that Brand.

Last updated March 31st, 2017.