General Information

Collections is another data point that enriches the Entertainment API by connecting titles that are part of a film series or media franchise. Using Collection Types, IVA has created another way to organize lists of content under umbrellas such as Shared Universe, Iconic Characters, Iconic Authors, etc. IVA clients can then show other titles related to the one their users are viewing, helping to power stronger recommendations and drive more engagement.

Review the definitions and examples below to see how to work with the Collections data within the Entertainment API. If you have any questions please reach out to our support team.


Related API Guides: Entertainment API, Common Data API

Open API/Swagger documentation can be found on the Entertainment API page.


Collection Search Parameters

A new Collection Search endpoint contained in the Common Metadata API has been introduced in order to search and ingest Collections. The available parameters for the Collection Search endpoint are detailed below.

Skip Integer used to skip Collections for paging.
Take Integer used to set the number of Collections returned per page.
Ids Comma-separated list of Collection Ids used to directly request Collections by their ID.
ParentCollectionIds Comma-separated list of Collection Ids used to request Collections that are children of the specified CollectionIds.
AnyIds Comma-separated list of Collection Ids used to request Collections either directly by their ID OR that are children of the specified CollectionIds.
ProgramIds Comma-separated list of Entertainment Program Ids used to request Collections containing the specified Entertainment Programs.
NameSearch String used to search the Name and Description property and return relevant Collections.
Types Comma-separated list of CollectionTypes used to filter the Collections returned to those of the specified CollectionTypes. The current available values for CollectionTypes are: SequentialWork, IconicCharacter, SharedUniverse, IconicAuthor, IconicTitle, IconicPerformer, IconicStudio, IconicBrand.
SearchAllTerms String used to search the all text properties of Collections to return relevant Collections.
NextPageToken Used for deep paging of records (beyond 10,000). Provide the NextPageToken returned from search results when using Timestamp sorting for optimal performance while paging large result sets. Skip is ignored when this parameter is provided.
SortBy Used to set sort order of results.
ModifiedRecordsSince Datetime used to filter Collections returned based on timestamp of last modification. This can be used in a regular update call to ensure Collections are updated in a client's data cache.

Collection Search Response

An example of an API response from the Collections Search is below:

            {
                "Score": 0,
                "Source": {
                  "Id": "Collection/1032",
                  "Name": "Superman (DCEU)",
                  "Types": [
                    "IconicCharacter",
                    "SequentialWork"
                  ],
                  "ParentCollectionIds": [
                    "Collection/1",
                    "Collection/3"
                  ],
                  "Items": [
                    {
                      "ProgramId": "Movie/19139",
                      "Sequence": 3,
                      "Modified": "2020-09-10T16:46:32.0000000Z"
                    },
                    {
                      "ProgramId": "Movie/3854",
                      "Sequence": 1,
                      "Modified": "2020-09-10T16:46:32.0000000Z"
                    },
                    {
                      "ProgramId": "Movie/4495",
                      "Sequence": 2,
                      "Modified": "2020-09-10T16:46:32.0000000Z"
                    }
                  ],
                  "Tags": [
                    "collection: dceu",
                    "dc extended universe",
                    "collection: superman",
                    "superhero",
                    "comics/heroes",
                    "collection: batman",
                    "based on comic",
                    "space/aliens"
                  ],
                  "MicroGenres": [
                    "superhero",
                    "superhero film",
                    "3d"
                  ],
                  "Subjects": [
                    "alien invasion",
                    "alien invasions s",
                    "christianity",
                    "coming-of-age",
                    "terrorism"
                  ],
                  "BasedOns": [
                    "the death of superman",
                    "justice league",
                    "superman"
                  ],
                  "Characters": [
                    "Metropolis Citizen",
                    "Martha Kent",
                    "Lois Lane",
                    "General Swanwick",
                    "Glen Woodburn",
                    "Major Carrie Farris",
                    "Pedestrian",
                    "Air Force Security",
                    "Wonder Woman / Diana Prince",
                    "Cyborg / Victor Stone"
                  ],
                  "Timestamp": "2020-09-09T20:56:12.0000000Z"
                },
                "Id": "Collection/1032"
              }
        

There are several metadata fields that make up a Collection object in the Entertainment Search response. They are described below:

Id String representing the CollectionId of the Collection.
Name String representing the Name of the Collection.
Types List of strings representing the CollectionTypes of the Collection.
ParentCollectionIds List of CollectionIds representing the parent Collection(s) of the Collection.
Items List of Entertainment Programs contained in the Collection. This includes the Entertainment ProgramId, a Sequence value if this is a sequenced collection, and a Modified timestamp representing the last time this CollectionItem was modified.
Tags List of string tags derived from the Entertainment Programs that are members of the Collection.
MicroGenres List of string microgenres derived from the Entertainment Programs that are members of the Collection.
Subjects List of string subjects derived from the Entertainment Programs that are members of the Collection.
BasedOns List of string based-ons derived from the Entertainment Programs that are members of the Collection.
Characters List of string characters derived from the Entertainment Programs that are members of the Collection.
Timestamp Datetime representing the last update on the Collection. A default timestamp of 0001-01-01 is found on Collections from our initial launch.

Entertainment Search Parameters

The Entertainment Search endpoint has introduced a couple of parameters offering options to explore the Collections metadata. Those parameters are detailed below:

CollectionIds A comma-separated list of CollectionIds that allows you to filter the Entertainment Programs returned to those programs contained in the specified Collections (either directly or through the Parent Collection). See below for details on Collections.
CollectionTypes A comma-separated list of CollectionTypes that allows you to filter the Entertainment Programs returned to those programs contained in Collections of the specified CollectionTypes. The current available values for CollectionTypes are: SequentialWork, IconicCharacter, SharedUniverse, IconicAuthor, IconicTitle, IconicPerformer, IconicStudio, IconicBrand.

Entertainment Search Response - Collections

Making use of the "Includes" parameter of the Entertainment Search endpoint by setting "Includes=Collections" will return the Collections array on each program that is a member of at least one Collection. An example of a Collections array in an API response is below:

        "Collections": [
            {
            "Id": "Collection/3",
            "Name": "Superman",
            "Description": "Based on the DC Comics character created by Jerry Siegel and Joe Shuster about an alien with super powers that defends earth",
            "Types": [
                "IconicCharacter"
            ],
            "Timestamp": "2020-09-09T20:48:01.0000000Z"
            },
            {
            "Id": "Collection/136",
            "Name": "DC Animated Movie Universe",
            "Description": "Based on characters created for DC Comics published by Warner Bros. Animation",
            "Types": [
                "SharedUniverse"
            ],
            "Timestamp": "2020-09-09T20:53:17.0000000Z"
            }
        ]
      

There are several metadata fields that make up a Collection object in the Entertainment Search response. They are described below:

Id String representing the CollectionId of the Collection.
Name String representing the Name of the Collection.
Description String containing a short description of the Collection.
Timestamp Datetime representing the last update on the Collection.

Collection Types Descriptions

The following are brief descriptions of the Collection Types found in our Collections metadata.

SharedUniverse This is multiple movies that are all taking place in the same universe. Examples include Marvel Cinematic Universe, Wizarding World, etc.
IconicCharacter This is when a character is found in multiple movies and is one readily recognized by the general population. Examples include Superman, Dracula, Freddy Krueger, James Bond, Sherlock Holmes, etc.
IconicTitle This is used when the title is what is most recognized and is used in number of films or TV shows. Examples include Mission: Impossible, Jaws, Toy Story, The Matrix, Hamlet, etc.
IconicAuthor This is used when the author’s works have a number of movies and/or TV shows made from their works. Examples include Stephen King, Shakespeare, Agatha Christie, Jules Verne, etc.
IconicStudio This is used when the studio releasing it has a particular expectation of what their content will be like. Examples include Disney Animated Features, Dreamworks Animated Films, Hammer Studios, etc.
IconicPerformer This is used when a performer(s) are known for a particular type of performance when appearing in a title. Examples of comedy duos such as Laurel Hardy, Abbot and Costello, Marx Brothers, or Astaire and Rogers.
IconicBrand Brands are sometimes known to offer movie and TV shows such as LEGO or National Lampoon.
SequentialWork Any titles that have a specific sequence number in its title or is part of a well known franchise would be considered a sequential work. This should be an additional type that is added to one of the above when applicable.