Collections Guide

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, Fabric Origin has created another way to organize lists of content under umbrellas such as Shared Universe, Iconic Characters, Iconic Authors, etc. Fabric Origin 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

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 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" 
  } 
 ]