Metadata

The metadata resource represents all of the custom metadata associated with any of the following Mediagenix On-Demand entities:

• Asset
• Audio Track
• Brand
• Contributor
• Deal
• Image
• Rendition
• Right
• Scheduling
• Subtitle
• Title
• Title Group (Series or Collections)

You can access and update the metadata of any of the previous entities just by following the metadata link of each of these resources.

One very important thing to note is that each account in Mediagenix On-Demand may have a different set of metadata fields. These are defined in a template within each account in Mediagenix On-Demand, so the output when calling this API may vary depending on the account. In fact, if the template changes, the API will also change automatically. This is very important to note when performing an integration; you should not assume the metadata nodes will always be there or that their name will never change!

An example of a metadata information could look like the following:

<?xml version='1.0' encoding='utf-8' ?>
<metadata type='document'>
  <title-episode-name>Episode 6</episode-name>
  <title-episode-number>6</episode-number>
  <title-slot-length>00:58:00</slot-length>
  <title-silent type="boolean">true</silent>
  <title-dvd-release type="datetime">2012-02-12T23:00:00Z</dvd-release>
  <title-actors type="array">
    <title-actor>Leonardo Di Caprio</title-actor>
    <title-actor>Kate Winslet</title-actor>
    <title-actor>Johnny English</title-actor>
  </title-actors>
</metadata>

{
  "resource_type": "metadata",
  "title_episode_name": "Episode 6",
  "title_episode_number": 6,
  "title_slot_length": "00:58:00",
  "title_silent": true,
  "title_dvd_release": "2012-02-12T23:00:00Z",
  "title_actors": [
    "Leonardo Di Caprio",
    "Kate Winslet",
    "Johnny English"
  ]
}

Updating metadata

When you issue a GET request to a title’s metadata URL (e.g. https://movida.bebanjo.net/api/titles/11824/metadata), you get something like:

<metadata type="document">
  <title-episode-name>Tuesday 25 May</episode-name>
  <title-episode-number>92</episode-number>
  <title-genre>entertainment</genre>
  <title-slot-length>01:00:00</slot-length>
  <title-running-time>00:45:00</running-time>
  <title-episode-short-description>Daily chat show with Jenna James.</episode-short-description>
  <title-episode-detail>Daily chat show with Jenna James.</episode-detail>
</metadata>

{
  "resource_type": "metadata",
  "title_episode_name": "Tuesday 25 May",
  "title_episode_number": 92,
  "title_genre": "entertainment",
  "title_slot_length": "01:00:00",
  "title_running_time": "00:45:00",
  "title_episode_short_description": "Daily chat show with Jenna James.",
  "title_episode_detail": "Daily chat show with Jenna James."
}

All you have to do to update the metadata is to send a similar XML/JSON to the same URL via a PUT request. You can send the whole document or part of it. Let’s say that you wanted to change the “episode number” only, then you would issue a PUT request to the same URL with an XML/JSON like the following as the body:

<metadata type="document">
  <title-episode-number>99</episode-number>
</metadata>

{
  "title_episode_number": 99
}

Let’s say that you have to update a multi-value metadata field. The process is mostly the same. You would send a PUT request with an XML/JSON, but in this case you would include attribute "type=array" in the metadata field. You have to include all values for that field as well, not only those values you want to add. And the order is preserved too:

<metadata type="document">
  <title-actors type="array">
    <title-actor>Leonardo Di Caprio</title-actor>
    <title-actor>Jed Bartlett</title-actor>
    <title-actor>Cedric Yarbrough</title-actor>
  </title-actors>
</metadata>

{
  "title_actors": [
    "Leonardo Di Caprio",
    "Jed Bartlett",
    "Cedric Yarbrough"
  ]
}

Please note also that, with XML/JSON representation, multi-value metadata fields will be represented as in the example before: the root node with the "type=array" will be plural (e.g. “title-actors”), while the inner nodes for each value will be singular (e.g. “title-actor”). This representation will always be used in GET requests and will always be accepted on PUT requests.

Empty metadata document

Note: Deprecated feature.

The metadata fields that haven’t ever been set won’t be present in the metadata document when you fetch it. For instance, the metadata of title just created will look like this:

<metadata type="document"></metadata>

{
  "resource_type": "metadata"
}

As the values of the different fields are set, either from the UI or from the API, the API will show the fields when fetching the metadata resource.

Please note that this behaviour is deprecated, and you shouldn’t rely on it in your integration. In the future, all the fields will always be present and they’ll be empty when no value will be assigned. For example:

<metadata type='document'>
  <title-episode-name nil="true"></episode-name>
  <title-episode-number nil="true"></episode-number>
  <title-episode-sort-name nil="true"></episode-sort-name>
  <title-genre nil="true"></genre>
  <title-slot-length nil="true"></slot-length>
  <title-running-time nil="true"></running-time>
  <title-episode-short-description nil="true"></episode-short-description>
  <title-episode-detail nil="true"></episode-detail>
  <title-source nil="true"></source>
  <title-rating nil="true"></rating>
  <title-silent type="boolean" nil="true"></silent>
  <title-dvd-release type="datetime" nil="true"></dvd-release>
  <title-actors type="array"></actors>
</metadata>

{
  "resource_type": "metadata",
  "title_episode_name": null,
  "title_episode_number": null,
  "title_episode_sort_name": null,
  "title_genre": null,
  "title_slot_length": null,
  "title_running_time": null,
  "title_episode_short_description": null,
  "title_episode_detail": null,
  "title_source": null,
  "title_rating": null,
  "title_silent": false,
  "title_dvd_release": null,
  "title_actors": []
}