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

Note: This resource links can be expanded using the expand option except blackout, right, trailer and promoted_content links.

A title is an individual title, like a specific program or movie, or an episode of a series.

It looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">1</id>
  <title>Forrest Gump</title>
  <name>Forrest Gump</name>
  <external-id>C5080530001</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.bebanjo.net/api/titles/1" rel="self"/>
  <link href="http://movida.bebanjo.net/api/titles/1/schedule" rel="schedule"/>
  <link href="http://movida.bebanjo.net/api/titles/1/availability_windows" rel="availability_windows"/>
  <link href="http://movida.bebanjo.net/api/titles/1/title_groups" rel="title_groups"/>
  <link href="http://movida.bebanjo.net/api/licensors/114" rel="licensor"/>
  <link href="http://movida.bebanjo.net/api/titles/1/images" rel="images"/>
  <link href="http://movida.bebanjo.net/api/titles/1/metadata" rel="metadata"/>
  <link href="http://movida.bebanjo.net/api/titles/1/blackouts" rel="blackouts"/>
  <link href="http://movida.bebanjo.net/api/titles/1/trailers" rel="trailers"/>
</title>

As you can see, a title has a schedule (which will contain all of the instances of that title in any of the available VoD platforms), and it also references its series, its licensor, its metadata, its images, and, if it’s a feature, it’s blackouts and it’s trailers. If the title has a title-type of trailer it can also have a link to the title it promotes with a rel of promoted_content.

The self link is pointing to the title itself, and it is a unique URL that will not change overtime.

Valid attributes

  • id (required): Movida internal identifier of the title. It shouldn’t be provided in the creation of the resource, because Movida will assign that value.
  • external-id (optional): the identifier of the title in the external system. If provided, it has to be unique in the scope of the company.
  • title-type (required): the type of title. Possible values are episode, feature, open, promo, ad, bumper and trailer.
  • episode-number (optional): the number of episode. This attribute only makes sense when the title is an episode and belongs to a series.
  • name (required): the name of the title.
  • title (read-only): the full name of the title. In the case of an episode, it includes both the episode number and the title name. This is a read-only attribute, PUT or POST requests including this attribute will fail.
  • tags (optional): the list of tags separated by commas of the title.

Get a list of all titles

To return a list of all titles in your account (this can be a bit massive - please note that at the moment pagination is not default), it would go like this:

$ curl --digest -u robot_user http://movida.bebanjo.net/api/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/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/licensors/29" rel="licensor"/>
    <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">30391</id>
    <title>The Green Lantern</title>
    <name>The Green Lantern</name>
    <external-id>C5150630007</external-id>
    <title-type>feature</title-type>
    <tags>Drama,Action</tags>
    <link href="http://movida.bebanjo.net/api/titles/30391" rel="self"/>
    <link href="http://movida.bebanjo.net/api/titles/30391/schedule" rel="schedule"/>
    <link href="http://movida.bebanjo.net/api/titles/30391/availability_windows" rel="availability_windows"/>
    <link href="http://movida.bebanjo.net/api/licensors/207" rel="licensor"/>
    <link href="http://movida.bebanjo.net/api/titles/30391/images" rel="images"/>
    <link href="http://movida.bebanjo.net/api/titles/30391/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 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 of your account.

Valid attributes

  • external_id: You can filter the list of titles by passing in an external_id. Because Movida was designed to integrate with external content management system, 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.

  • pagination - Note that by default, this is not paginated endpoint for the Title resource. 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.

Get a title by external_id

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

$ curl --digest -u robot_user http://movida.bebanjo.net/api/titles?external_id=C5147630001

Which would filter by the passed external_id like:

<?xml version="1.0" encoding="UTF-8"?>
<titles type="array">
  <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/licensors/29" rel="licensor"/>
    <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>
</titles>

Get a list of all trailers on a title

To return a list of all trailers for a title, 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/titles/30391/trailers?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/titles/30391/trailers?pagination=true&page=2"/>
  <title>
    <id type="integer">73</id>
    <title>Trailer 1</title>
    <name>Trailer 1</name>
    <external-id>C5147630001</external-id>
    <title-type>trailer</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/titles/73/images" rel="images"/>
    <link href="http://movida.bebanjo.net/api/titles/73/metadata" rel="metadata"/>
    <link href="http://movida.bebanjo.net/api/titles/30391" rel="promoted_content"/>
  </title>
  <title>
    <id type="integer">74</id>
    <title>Trailer 2</title>
    <name>Trailer 2</name>
    <external-id>C5147630002</external-id>
    <title-type>trailer</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"/>
    <link href="http://movida.bebanjo.net/api/titles/30391" rel="promoted_content"/>
  </title>
</titles>

Note: With enabled pagination, 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 trailers for a title.

Valid attributes

You can filter the list of titles returned using the following attributes:

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

Get a specific title

This is a good way to recover information about a specific title. 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 http://movida.bebanjo.net/api/titles/73
<?xml version='1.0' encoding='utf-8' ?>
<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/title_groups" rel="title_groups"/>
  <link href="http://movida.bebanjo.net/api/licensors/29" rel="licensor"/>
  <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>

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.

$ curl --digest -u robot_user http://movida.bebanjo.net/api/titles/73?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>
  <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">
    <schedule>
      <link href="http://movida.bebanjo.net/api/titles/73/schedule/schedulings" rel="schedulings">
        <schedulings type="array">
          <scheduling>
            <id type="integer">23817</id>
            <put-up type="datetime">2009-10-01T00:00:00+01:00</put-up>
            <take-down type="datetime">2010-12-22T23:59:59+00:00</take-down>
            <scheduling-type>archive</scheduling-type>
            <rights-status>cleared</rights-status>
            <tags>Drama,Action</tags>
            <link href="http://movida.bebanjo.net/api/schedulings/23817" rel="self"/>
            <link href="http://movida.bebanjo.net/api/title_groups/41" rel="title_group"/>
            <link href="http://movida.bebanjo.net/api/titles/73" rel="title"/>
            <link href="http://movida.bebanjo.net/api/schedulings/23817/assets" rel="assets"/>
            <link href="http://movida.bebanjo.net/api/platforms/1" rel="platform"/>
          </scheduling>
        </schedulings>
      </link>
      <link href="http://movida.bebanjo.net/api/titles/73" rel="title"/>
    </schedule>
  </link>
  <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/title_groups" rel="title_groups"/>
  <link href="http://movida.bebanjo.net/api/licensors/29" rel="licensor"/>
  <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>

Creating titles

For creating titles, you just need to POST a proper XML title representation (similar to the ones you get when fetching a title) to the proper URL. That URL can be found in a link whose rel is titles, like the one found in the API root (for creating titles which don’t belong to any series) or in any series (for creating titles belonging to that series). The only required field is the name, the rest are optional.

Creating a standalone title AKA feature

For example, this POST would create a film (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat title.xml
<title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/4"/>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
</title>

Note: The licensor URL must be of one licensor that already exists in the system, otherwise it will default to “No Licensor”, since it is optional. See how to create licensors in the licensor page.

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @title.xml "http://movida.bebanjo.net/api/titles"

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

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">4</id>
  <title>13 Assassins</title>
  <name>13 Assassins</name>
  <external-id>123456</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link rel="self" href="http://movida.bebanjo.net/api/titles/4"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/titles/4/schedule"/>
  <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/4"/>
  <link rel="images"   href="http://movida.bebanjo.net/api/titles/4/images"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/titles/4/metadata"/>
</title>

Creating a trailer

For example, this POST would create a trailer for the title created above (we’ll again use $ curl’s @ option, which reads data to be posted from a file):

$ cat trailer.xml
<title>
  <name>13 Assassins (Trailer)</name>
  <external-id>TR123456</external-id>
  <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/4"/>
  <title-type>trailer</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.bebanjo.net/api/titles/4" rel="promoted_content" />
</title>

Note: The promoted_content URL must be of one title that already exists in the system.

Note: The licensor URL must be of one licensor that already exists in the system, otherwise it will default to “No Licensor”, since it is optional. See how to create licensors in the licensor page.

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @trailer.xml "http://movida.bebanjo.net/api/titles"

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

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">5</id>
  <title>13 Assassins (Trailer)</title>
  <name>13 Assassins (Trailer)</name>
  <external-id>TR123456</external-id>
  <title-type>trailer</title-type>
  <tags>Drama,Action</tags>
  <link rel="self" href="http://movida.bebanjo.net/api/titles/5"/>
  <link rel="schedule" href="http://movida.bebanjo.net/api/titles/5/schedule"/>
  <link rel="licensor" href="http://movida.bebanjo.net/api/licensors/4"/>
  <link rel="images"   href="http://movida.bebanjo.net/api/titles/5/images"/>
  <link rel="metadata" href="http://movida.bebanjo.net/api/titles/5/metadata"/>
  <link rel="promoted_content" href="http://movida.bebanjo.net/api/titles/4"/>
</title>

Creating an episode to an existing series

To create an episode of a series, you only need to POST the title XML to the URL in the link rel=titles of the series you want to add the episode to.

Assuming the URL for the episodes of a series is http://movida.bebanjo.net/api/title_groups/1/titles and the following XML:

$ cat episode.xml
<title>
  <name>Episode 1</name>
  <external-id>123456</external-id>
  <episode-number>1</episode-number>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
</title>

The following command would create it as part of the series’ episodes:

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X POST -d @episode.xml "http://movida.bebanjo.net/api/title_groups/1/titles"

This would return the XML of the new episode, note how it references the series we’ve just associated it to:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">30392</id>
  <title>E01, Episode 1</title>
  <name>Episode 1</name>
  <episode-number type="integer">1</episode-number>
  <external-id>123456</external-id>
  <title-type>episode</title-type>
  <tags>Drama,Action</tags>
  <link href="https://staging-movida.bebanjo.net/api/titles/4" rel="self"/>
  <link href="http://movida.bebanjo.net/api/titles/30392/schedule" rel="schedule"/>
  <link href="http://movida.bebanjo.net/api/titles/30392/availability_windows" rel="availability_windows"/>
  <link href="http://movida.bebanjo.net/api/title_groups/1" rel="series"/>
  <link href="http://movida.bebanjo.net/api/titles/30392/title_groups" rel="title_groups"/>
  <link href="http://movida.bebanjo.net/api/licensors/114" rel="licensor"/>
  <link href="http://movida.bebanjo.net/api/titles/30392/images" rel="images"/>
  <link href="http://movida.bebanjo.net/api/titles/30392/metadata" rel="metadata"/>
</title>

Updating titles

You can update titles issuing a PUT request to the URL of a given title, as the following example illustrates. This example only updates the title’s name, but also the external-id, the licensor, the promoted_content and the episode number can be updated.

Note: The external ID can be updated only if it’s blank, if it already has a value it can’t be changed.

$ cat title.xml
<title>
  <name>13 Assassins (English version)</name>
</title>

Now we send the XML as the body of a PUT request to the title’s URL:

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X PUT -d @title.xml "http://movida.bebanjo.net/api/titles/4"

The PUT request would return the updated XML of the title:

<?xml version="1.0" encoding="UTF-8"?>
<title>
  <id type="integer">4</id>
  <title>13 Assassins (English version)</title>
  <name>13 Assassins (English version)</name>
  <external-id>C5144140351</external-id>
  <title-type>feature</title-type>
  <tags>Drama,Action</tags>
  <link href="http://movida.bebanjo.net/api/titles/4" rel="self"/>
  <link href="http://movida.bebanjo.net/api/titles/4/schedule" rel="schedule"/>
  <link href="http://movida.bebanjo.net/api/titles/4/availability_windows" rel="availability_windows"/>
  <link href="http://movida.bebanjo.net/api/titles/4/title_groups" rel="title_groups"/>
  <link href="http://movida.bebanjo.net/api/licensors/4" rel="licensor"/>
  <link href="http://movida.bebanjo.net/api/titles/4/images" rel="images"/>
  <link href="http://movida.bebanjo.net/api/titles/4/metadata" rel="metadata"/>
</title>

Deleting titles

The following example shows how to destroy a particular title. Only a DELETE HTTP request to its URL is required:

$ curl -u robot:yourpassword --digest -H "Content-Type: application/xml" -X DELETE "http://movida.bebanjo.net/api/titles/4"

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

Deleting a title causes some of its related resources to be removed:

  • Assets
  • Availability windows
  • Linear schedulings
  • Schedulings

Last updated July 07th, 2017.