Skip to content

VOD catalog Specification

Specification

Field Type Description Required
metadata Metadata[] Yes

Metadata type

Field Type Description Required
availabilities Availability[] Yes
credits Credit[] Cast and crew.
descriptions Description[] Localized descriptions of the content.
external_ids ExternalID[] External IDs that the partner may choose to be shared with to better match content.
genre string[] Genre list.
id string Uniquely identifies the content. Immutable value. Yes
images Image[]
ratings Rating[] List of ratings by rating systems.
release_date string Date in ISO 8601 format (only date segment) Yes
runtime number Duration of the content, in minutes.
series_info SeriesInfo This field is populated when the metadata belongs to a season or episode. Yes for season and episode
titles Title[] Localized titles of the content. Yes
type enum Type of the metadata object. Can either be movie, show, season or episode. Yes

Availability type

Field Type Description Required
audio_languages string[] List of available audio language tracks, in ISO 639-1 format - always two-letter lowercase strings. Yes
available_ending string Date in ISO 8601 format (including time). Yes
available_starting string Date in ISO 8601 format (including time). Yes
countries string[] List of countries in ISO 3166-1 alpha-2 codes (capitalized). Yes
delivery_method enum Always vod for VOD catalogs. Yes
monetization_type enum Can either be ads (AVOD availability) or rentals (TVOD availability). Yes
price_currency string Currency code in ISO 4217 format. This is only defined when monetization_type is rentals. Yes for rentals
price number Price value for the rental availability. This is only defined when monetization_type is rentals. Yes for rentals
subtitle_languages string[] List of available subtitle language tracks, in ISO 639-1 format - always two-letter lowercase strings.
url string Public page URL to our content.

Credit type

Field Type Description Required
person_image string URL to the person's image
person_name string Yes
role string Role that the person performs in the title.
type enum Can either be actor or director. Yes

Description type

Field Type Description Required
country string Country of the description, in ISO 3166-1 alpha-2 code. Yes
description string Description of the content in the language specified in language field. Yes
language string Description language in ISO 639-1 format. This can be undefined. Yes

ExternalID type

Field Type Description Required
id string Identifier of the content according to the source specified in type. Yes
type string Source of the identifier. Can either be gracenote, imdb or tmdb. Yes

Image type

Field Type Description Required
height number Height in pixels
language string Image language in ISO 639-1 format. Can be undefined if the language is neutral.
type enum Can either be coverPoster (vertical) or coverArt (horizontal) Yes
url string URL to the image resource Yes
width number Width in pixels

Rating type

Field Type Description Required
country string Country of the rating, in ISO 3166-1 alpha-2 code. Yes
rating string Rating value. Yes
rating_body string Code of the rating system. For instance, for US this value is MPAA. Yes

SeriesInfo type

Field Type Description Required
episode_number number Episode order. This field is only defined on a season. Yes for episode
number_of_episodes number Number of episodes in the season. This field is only defined on a season. Yes for season
season_id string ID of the season an episode belongs to. Yes for episode
season_number number Season order. This field is only defined on a season. Yes for season
show_id string ID of the show an episode or season belongs to. Yes for season and episode

Title type

Field Type Description Required
country string Country of the title, in ISO 3166-1 alpha-2 code. Yes
language string Title language in ISO 639-1 format. This can be undefined. Yes
title string Title of the content in the language specified in language field. Yes

Examples

Movie example

{
  "availabilities": [
    {
      "audio_languages": ["en"],
      "available_ending": "9999-12-31T23:59:59.999Z", //(1)!
      "available_starting": "2021-09-24T21:18:42.878Z",
      "countries": [
        //(5)!
        "BR",
        "ES",
        "FR",
        "IT",
        "RU",
        "US"
      ],
      "delivery_method": "vod",
      "monetization_type": "ads", //(2)!
      "subtitle_languages": ["en"],
      "url": "https://watch.plex.tv/movie/the-criminal-mind?autoplay=1&utm_content=5d776b1323d5a3001f50c573&utm_medium=deeplink&utm_source=plex-v2-catalog" //(3)!
    }
  ],
  "credits": [
    {
      "person_image": "https://metadata-static.plex.tv/5/people/58c9a1514d5cd13965b49646cfbef340.jpg",
      "person_name": "Frank Rossi",
      "role": "Nick August",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/people/5d77682c2ec6b5001f6bad46.jpg",
      "person_name": "Ben Cross",
      "role": "Carlo Augustine",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/c/people/cb47abfe9fee04c8333307b26a7f936c.jpg",
      "person_name": "Tahnee Welch",
      "role": "Gabrielle Dupré",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/4/people/48996711021f48cc31826dfa4bdd3c4c.jpg",
      "person_name": "Lance Henriksen",
      "role": "Agent Winslow",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/people/5d77682954f42c001f8c2dec.jpg",
      "person_name": "Joseph Ruskin",
      "role": "Manny Kohen",
      "type": "actor"
    },
    {
      "person_name": "Joseph Vittorie",
      "role": "director",
      "type": "director"
    }
  ],
  "descriptions": [
    {
      "description": "A young District Attorney pays a visit to his older brother, who is a Mafia boss. The older brother forces his girlfriend and his brother to witness a double murder, then sets them up so an Asian organized crime gang believes they committed the murders.",
      "language": "en"
    }
  ],
  "genres": ["Drama", "Crime", "Action"],
  "id": "5d776b1323d5a3001f50c573",
  "images": [
    {
      "height": 1500,
      "language": "en",
      "type": "coverPoster",
      "url": "https://image.tmdb.org/t/p/original/w1Klps7wo0RqE154iQAjyQyQwj8.jpg",
      "width": 1000
    },
    {
      "height": 2160,
      "language": "en",
      "type": "coverArt",
      "url": "https://metadata-static.plex.tv/1/gracenote/1c4dc22b12d9a5286e24db0c86377e9e.jpg",
      "width": 3840
    }
  ],
  "ratings": [
    {
      "country": "US",
      "rating": "R",
      "rating_body": "MPAA"
    }
  ],
  "release_date": "1996-12-01",
  "runtime": 92,
  "titles": [
    //(4)!
    {
      "country": "BR",
      "title": "Herdeiros da Máfia"
    },
    {
      "country": "ES",
      "title": "Mente criminal"
    },
    {
      "country": "FR",
      "title": "Aux frontières du crime"
    },
    {
      "country": "IT",
      "title": "Inganno criminale"
    },
    {
      "country": "RU",
      "title": "Преступный склад ума"
    },
    {
      "country": "US",
      "title": "The Criminal Mind"
    }
  ],
  "type": "movie"
}
  1. This kind of availability represents an boundless availability, content that is always available.
  2. AVOD availability.
  3. This URL takes directly to the playback page.
  4. We can see different titles depending on the region.
  5. Available only on five countries.

Series example

{
  "availabilities": [
    {
      "audio_languages": ["en"],
      "available_ending": "2024-08-01T06:59:00.000Z",
      "available_starting": "2023-10-01T07:00:00.000Z",
      "countries": ["AS", "FM", "GB", "GU", "MH", "MP", "PR", "PW", "RS", "UM", "US", "VI"],
      "delivery_method": "vod",
      "monetization_type": "ads",
      "subtitle_languages": ["en"],
      "url": "https://watch.plex.tv/show/everybody-hates-chris?autoplay=1&utm_content=5d9c0801e98e47001eb05302&utm_medium=deeplink&utm_source=plex-v2-catalog"
    }
  ],
  "credits": [
    {
      "person_image": "https://metadata-static.plex.tv/b/people/b5e9e7aab317d4b0c4b22ea0dbdd1ce8.jpg",
      "person_name": "Tyler James Williams",
      "role": "Chris",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/0/people/0cb169fcca22991795718edfdd16f827.jpg",
      "person_name": "Terry Crews",
      "role": "Julius",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/3/people/326c5831f28bb2b6af4074a32b8cef70.jpg",
      "person_name": "Vincent Martella",
      "role": "Greg Wuliger",
      "type": "actor"
    }
  ],
  "descriptions": [
    {
      "description": "Todo el Mundo Odia a Chris (Everybody Hates Chris) es una sitcom estadounidense inspirada en las experiencias vividas durante la adolescencia del comediante Chris Rock (que también es el narrador), mientras crecía en el barrio de Bedford-Stuyvesant, del distrito de Brooklyn en Nueva York de 1982 a 1987.",
      "language": "es"
    },
    {
      "description": "Chris is a teenager growing up as the eldest of three children in Brooklyn, New York during the early 1980s. Uprooted to a new neighborhood and bused to a predominantly white middle school two-hours away by his strict, hard-working parents, Chris struggles to find his place while keeping his siblings in line at home and surmounting the challenges of junior high.",
      "language": "en"
    }
  ],
  "genres": ["Comedy", "Drama", "Family", "Children", "Music"],
  "id": "5d9c0801e98e47001eb05302",
  "images": [
    {
      "height": 1600,
      "language": "en",
      "type": "coverPoster",
      "url": "https://image.tmdb.org/t/p/original/3FjakKDEuaO8FpR1qJctV6njqYy.jpg",
      "width": 1067
    },
    {
      "height": 1080,
      "type": "coverArt",
      "url": "https://metadata-static.plex.tv/c/gracenote/cd162dad5f2e827e2f427acd10460889.jpg",
      "width": 1920
    }
  ],
  "ratings": [
    {
      "country": "GB",
      "rating": "12",
      "rating_body": "BBFC"
    },
    {
      "country": "US",
      "rating": "TV-PG",
      "rating_body": "USA Parental Rating"
    }
  ],
  "release_date": "2005-09-22",
  "titles": [
    {
      "country": "PR",
      "title": "Todo el mundo odia a Chris"
    },
    {
      "country": "RS",
      "title": "Сви мрзе Криса"
    },
    {
      "country": "US",
      "title": "Everybody Hates Chris"
    }
  ],
  "type": "show"
}

Season example

{
  "availabilities": [
    {
      "audio_languages": ["en"],
      "available_ending": "2024-08-01T06:59:00.000Z",
      "available_starting": "2023-10-01T07:00:00.000Z",
      "countries": ["AS", "FM", "GB", "GU", "MH", "MP", "PR", "PW", "RS", "UM", "US", "VI"],
      "delivery_method": "vod",
      "monetization_type": "ads",
      "subtitle_languages": ["en"],
      "url": "https://watch.plex.tv/show/everybody-hates-chris/season/4?autoplay=1&utm_content=5d9c094b7b5c2e001e668fb4&utm_medium=deeplink&utm_source=plex-v2-catalog"
    }
  ],
  "credits": [
    {
      "person_image": "https://metadata-static.plex.tv/b/people/b5e9e7aab317d4b0c4b22ea0dbdd1ce8.jpg",
      "person_name": "Tyler James Williams",
      "role": "Chris",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/0/people/0cb169fcca22991795718edfdd16f827.jpg",
      "person_name": "Terry Crews",
      "role": "Julius",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/3/people/326c5831f28bb2b6af4074a32b8cef70.jpg",
      "person_name": "Vincent Martella",
      "role": "Greg Wuliger",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/c/people/c77a584f8084d46a362cf8162a3c10ed.jpg",
      "person_name": "Tichina Arnold",
      "role": "Rochelle",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/people/5d77682beb5d26001f1de90d.jpg",
      "person_name": "Imani Hakim",
      "role": "Tonya",
      "type": "actor"
    }
  ],
  "genres": ["Comedy", "Drama", "Family", "Children", "Music"],
  "id": "5d9c094b7b5c2e001e668fb4",
  "images": [
    {
      "height": 1426,
      "language": "en",
      "type": "coverPoster",
      "url": "https://image.tmdb.org/t/p/original/3v9JOQKY0H7mhk76Tk8xa4Rm883.jpg",
      "width": 951
    },
    {
      "height": 1080,
      "type": "coverArt",
      "url": "https://metadata-static.plex.tv/9/gracenote/97eb111da1ed163c2d384736d789d88e.jpg",
      "width": 1920
    }
  ],
  "ratings": [
    {
      "country": "GB",
      "rating": "12",
      "rating_body": "BBFC"
    },
    {
      "country": "US",
      "rating": "TV-PG",
      "rating_body": "USA Parental Rating"
    }
  ],
  "release_date": "2008-10-03",
  "series_info": {
    //(1)!
    "number_of_episodes": 22,
    "season_number": 4,
    "show_id": "5d9c0801e98e47001eb05302"
  },
  "titles": [
    {
      "country": "US",
      "title": "Season 4"
    }
  ],
  "type": "season"
}
  1. Information about the series, concerning the season: total number of episodes in that season, season order (4) and the corresponding show ID.

Episode example

{
  "availabilities": [
    {
      "audio_languages": ["en"],
      "available_ending": "2024-08-01T06:59:00.000Z",
      "available_starting": "2023-10-01T07:00:00.000Z",
      "countries": ["AS", "GU", "MP", "UM", "FM", "MH", "PW", "PR", "RS", "GB", "US", "VI"],
      "delivery_method": "vod",
      "monetization_type": "ads",
      "subtitle_languages": ["en"],
      "url": "https://watch.plex.tv/show/everybody-hates-chris/season/4/episode/8?autoplay=1&utm_content=5d9c0cc43c3f87001f379ac7&utm_medium=deeplink&utm_source=plex-v2-catalog"
    }
  ],
  "credits": [
    {
      "person_image": "https://metadata-static.plex.tv/b/people/b5e9e7aab317d4b0c4b22ea0dbdd1ce8.jpg",
      "person_name": "Tyler James Williams",
      "role": "Chris",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/0/people/0cb169fcca22991795718edfdd16f827.jpg",
      "person_name": "Terry Crews",
      "role": "Julius",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/3/people/326c5831f28bb2b6af4074a32b8cef70.jpg",
      "person_name": "Vincent Martella",
      "role": "Greg Wuliger",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/c/people/c77a584f8084d46a362cf8162a3c10ed.jpg",
      "person_name": "Tichina Arnold",
      "role": "Rochelle",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/people/5d77682beb5d26001f1de90d.jpg",
      "person_name": "Imani Hakim",
      "role": "Tonya",
      "type": "actor"
    },
    {
      "person_image": "https://metadata-static.plex.tv/3/people/32ba672ecc755ed61a84d519f306492b.jpg",
      "person_name": "Ted Wass",
      "role": "director",
      "type": "director"
    }
  ],
  "descriptions": [
    {
      "description": "When the dorkiest girl in school, who everyone calls \"Big Bird\", asks Chris out on a date, he agrees but only to spare her feelings. He soon realizes after spending time with her that he genuinely likes her.",
      "language": "en"
    }
  ],
  "genres": ["Comedy", "Drama", "Family", "Children", "Music"],
  "id": "5d9c0cc43c3f87001f379ac7",
  "images": [
    {
      "height": 1080,
      "language": "en",
      "type": "coverPoster",
      "url": "https://image.tmdb.org/t/p/original/ehMeJdoIMoMLfGqBkTitdgY7jqN.jpg",
      "width": 1920
    }
  ],
  "ratings": [
    {
      "country": "GB",
      "rating": "12",
      "rating_body": "BBFC"
    },
    {
      "country": "US",
      "rating": "TV-PG",
      "rating_body": "USA Parental Rating"
    }
  ],
  "release_date": "2008-11-21",
  "runtime": 20,
  "series_info": {
    //(1)!
    "episode_number": 8,
    "season_number": 4,
    "season_id": "5d9c094b7b5c2e001e668fb4",
    "show_id": "5d9c0801e98e47001eb05302"
  },
  "titles": [
    {
      "country": "US",
      "title": "Everybody Hates Big Bird"
    }
  ],
  "type": "episode"
}
  1. Information about the series and season IDs and the season and episode orders.