General Information

IVA Entertainment IDs are your all-access pass to the IVA Entertainment universe of rich metadata, images, video, and so much more! In order to ensure you are always connected, we recommend that you warehouse IVA Entertainment IDs in your catalog. The Entertainment Match endpoint allows you to make use of basic metadata from your catalog to match to IVA'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 an IVA Entertainment record. Those parameters are detailed below:

ProgramType The type of Program to be matched: "Movie" or "Show".

NOTE: IVA ProgramType "Show" refers to all television content that is episodic in nature (includes seasons and episodes). IVA 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.

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"):


Entertainment Match Scoring
Criteria Score Year +/- 1 Exact Year
Exact title, cast & director 90 97 100
Exact title, cast OR director 70 77 80
Exact title only 50 57 60
 
Fuzzy title, cast & director 85 92 95
Fuzzy title, cast OR director 65 72 75
Fuzzy title only 45 52 55

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
        &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": [
                ...
            ]
        }