Docs Menu

Code Samples

Implementation Guides

Integrations

Metadata Match Guide

General Information

Fabric Origin Entertainment IDs are your all-access pass to the Fabric Origin Entertainment universe of rich metadata, images, video, and so much more! In order to ensure you are always connected, we recommend that you warehouse Fabric Origin Entertainment IDs in your catalog. The Entertainment Match endpoint allows you to make use of basic metadata from your catalog to match to Fabric Origin's rich metadata and receive back a matched Entertainment program. Matching metadata to metadata is always the best option to allow for the strongest match rates regardless of from where your basic metadata originates and it does not rely on the existence of and matching processes of third-party sources.

Review the definitions and examples below to see how to work with the Entertainment Match endpoint 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.

Entertainment Match Parameters

The Entertainment Match endpoint has several parameters offering options of basic metadata to pass for the purpose of matching to a Fabric Origin Entertainment record. Those parameters are detailed below:

  • ProgramType - The type of Program to be matched: "Movie" or "Show". NOTE: Fabric Origin ProgramType "Show" refers to all television content that is episodic in nature (includes seasons and episodes). Fabric Origin ProgramType "Movie" includes all other non-episodic content from theatrical movies to direct-to-physical movies to "TV Movies", "TV Specials", and all other one-off style television content that does not include seasons and episodes.

  • Title - The Title of the Program to be matched. This Title and the Alternate Titles below are used together for either Exact or Fuzzy Title matching. (See StringDistance parameter below.)

  • AlternateTitles - A comma-separated list of Alternate Titles of the Program to be matched. These Alternate Titles and Titles are used together for either Exact or Fuzzy Title matching. (See StringDistance parameter below.)

  • Year - The Release Year of the Program to be matched. For Shows, this is the year of the first episode's release. The matching algorithm will limit all potential match candidates to within this given Year +/- 1 year. If you wish to expand the list of potential match candidates beyond that, you can elect to not pass a Year.

  • Cast - A comma-separated list of Actors from the Program to be matched.

  • Producers - A comma-separated list of Producers and/or Executive Producers from the Program to be matched.

  • Directors - A comma-separated list of Directors from the Program to be matched.

  • Description - The Description of the Program to be matched. This is used to extract potential names of Contributors from the text.

  • ReleaseDate - The Original Release Date of the Program to be matched. This is used as "BONUS" in the matching algorithm ONLY if a Program to be matched results in a score between 50 and 75. In this case, if the Original Release Date of the Program matches this parameter the match score is bumped to a 79.

  • StringDistance - The acceptable difference in the characters of the string used to match Titles that will still be considered a Fuzzy match. The default StringDistance is 4. This can be set to 0 to disallow Fuzzy Title matching.

  • Includes - A comma-separated list of which available sub-objects are returned. Available Options: Releases, Contributors, AlternateTitles, Descriptions, ExternalIds, All, None (Default is "All".) NOTE: The Includes list is additive therefore if "All" or "None" are passed in a list with others, "All" supersedes everything and "None" is always superseded.

Entertainment Match Results

The Entertainment Match endpoint allows you to pass several pieces of metadata returns program matches with an assigned score.

The assigned match score is determined as follows (scores highlighted in Green are considered "matches"):

EXAMPLE: Entertainment Match Response

In this example, we want to match to the 2015 film "Maggie" starring Arnold Schwarzenegger and Abigail Breslin and directed by Henry Hobson.

First, we will demonstrate the result of simply passing the two required parameters of ProgramType and Title. The result below shows the match was NOT considered successful because the limited metadata passed returned more than one option that could not be programmatically distinguished. (ProgramMatches list removed for conciseness.)

https://ee.iva-api.com/api/Entertainment/Match/?ProgramType=Movie 
&Title=Maggie&year=2015&cast=arnold+Schwatzenegger,abigail+breslin,JD+Evermore 
&subscription-Key={YourKey}
{ 
"Score": 50, 
"Success": false, 
"Description": "Multiple matches were found, check data for conflicts or duplicates.", 
"ProgramMatches": [ ... ] 
}

There are several fields returned in the Entertainment Match response. They are described below:

  • Score - The score that represents the results of the match. The meaning of the score is detailed in the table above.

  • Success - This will be true provided one match candidate is determined to be the better than all others. A result of false is produced when either more than one match candidate is found and cannot be programmatically distinguished OR no match candidates are found.

  • Description - A brief description of the result of the matching algorithm.

  • ProgramMatches - An array of the match candidates. In a successful match, this will only be ONE Entertainment program. Several sub-objects of the Entertainment Program are included for the purposes of confirming the match: ProgramType, Title, OriginalTitle, OriginalReleaseDate, Releases, Contributors, AlternateTitles, Descriptions, ExternalIds, etc. Be sure to collect the Entertainment ID from here!

Next, we will demonstrate the result of passing ProgramType, Title, AND Year. The result below shows the match WAS considered successful because the addition of the Year made it so the match candidates could be distinguished and ONE candidate was identified with the highest score. Note that the score is 60 and according to the score table above a 60 is not highlighted green due to our minimum confidence level looking for at least 1 Contributor to be included. (ProgramMatches list removed for conciseness.)

https://ee.iva-api.com/api/Entertainment/Match/?ProgramType=Movie 
&Title=Maggie 
&Year=2015 
&subscription-Key={YourKey}
{ 
"Score": 60, 
"Success": true, 
"Description": "Single match found at this score.", 
"ProgramMatches": [ ... ] 
}

Finally, we will include ProgramType, Title, Year, AND Cast and Director. The result below shows the match WAS considered successful and the score is 100 because we have an Exact Title, Exact Year, and at least 1 matching Actor and 1 matching Director. (ProgramMatches list removed for conciseness.)

https://ee.iva-api.com/api/Entertainment/Match/?ProgramType=Movie 
&Title=Maggie 
&Year=2015 
&Cast=Arnold Schwarzenegger, Abigail Breslin 
&Directors=Henry Hobson 
&subscription-Key={YourKey}
{ 
"Score": 100, 
"Success": true, 
"Description": "Single match found at this score.", 
"ProgramMatches": [ ... ] 
}