- Documentation
- Key Concepts
- Release Notes
Data Dictionary - Title
titleId
The unique IMDb ID for the title in question. Each IMDb ID appears exactly once.
remappedTo
It is possible that two IMDb IDs can be created for a single entity within our system before IMDb identify that they actually represent the same person or title. When this happens, we maintain the data associated with both identifiers in the data set, duplicating the data. If there are duplicate title entities for a title, remappedTo provides the IMDb ID of the primary title entity for this title.
See “Duplicate ID” in the “Changes to Entities and Resolving IDs” section of “Key Concepts” for more information.
originalTitle
The original title text of the title, normally what the title is known as in its original country of release.
akas
A list of all available alternative title texts by which this title is also known. Here to help with matching the IMDb title to any other title identifier you may have. Each title is listed with additional information about the usage of that title text, e.g. what country it is from, and what language it is used in.
Example
{
"akas": [
...
{
"country": "TR",
"language": "tr",
"title": "12 Öfkeli Adam"
},
...
]
}
titleDisplay
A list of alternative title display texts by which this title is also known. Each display text is listed with additional information about the usage of that display text, e.g. what country it is from, and what language it is used in. This is a subset of title akas, curated to only contain the title texts for each language and country which are best for displaying to customers.
Example
{
"originalTitle": "12 Angry Men",
"titleDisplay": [
{
"country": "AE",
"title": "12 Angry Men"
},
{
"country": "AU",
"title": "12 Angry Men"
},
{
"country": "DE",
"title": "Die zwölf Geschworenen"
},
{
"country": "CSHH",
"language": "cs",
"title": "Dvanáct rozhněvaných mužů"
},
...
]
}
awards
A list of awards that this title has won or been nominated for. This includes the name and category of the award, the name and year of the award event, the names who have been nominated and whether the title won the award. Note that winner
may be false because the title is known not to have won the award (where the awards event occured in the past) or because the winner is not yet known (where the awards event occurs in the future, but the nominations have been announced). If 'winner' is true that means the awards event has already occured, and the title won the award. Please also note that names
may be missing from the record in case the nomination is not related to a specific person (e.g. "Best Single Documentary" - Broadcasting Press Guild Award).
Example
{
"awards": [
{
"awardName": "Oscar",
"category": "Best Picture",
"event": "Academy Awards, USA",
"names": [
"nm0000020",
"nm0741627"
],
"winner": false,
"year": 1958
},
...
]
}
creditsByCategory
The credits for this title organized by category. Each entry in this list represents a single category and gives you a list of credits within that category. For cast credits we include the roles that the person played, the billing they had in the end credits (if available) and sometimes the creditedAs
field in case where the onscreen credit was using a different name. For crew credits we include the more specific "jobs" that the person was credited with if applicable. Lists of credits, roles, and jobs are each in on-screen credits order.
Credits can have a list of attributes that contain additional data about a specific credit (e.g. "uncredited", "voice", etc.).
Additional information about these attributes can be found on the IMDb help site.
For series we include anyone who is credited on any episode. To get full information on which episodes were worked on by a specific person, look at the episode credits.
Example
A crew category
{
"creditsByCategory": [
{
"category": "sound_department",
"credits": [
{
"jobs": ["sound"],
"nameId": "nm0322302"
},
{
"attributes": ["uncredited"],
"jobs": ["re-recording mixer"],
"nameId": "nm0334505"
}
]
},
...
]
}
A cast category
{
"creditsByCategory": [
{
"category": "cast",
"credits": [
{
"billing": 1,
"category": "actor",
"nameId": "nm0000842",
"roles": ["Juror 1"]
},
{
"billing": 2,
"category": "actor",
"nameId": "nm0275835",
"roles": ["Juror 2"]
},
...
{
"attributes": ["uncredited"],
"category": "actor",
"nameId": "nm0094036",
"roles": ["Judge"]
},
...
]
},
...
]
}
principalCastMembers
A short list of the most important cast credits for this title. This is always a subset of the cast from the creditsByCategory
list, but the selection and order is determined by IMDb. Often it is similar to top-billed cast but it can be different, for example if the title credits are in order of appearance or alphabetical. For more details see IMDb help site. Also includes the role or roles played (in on-screen credits order), the billing in the full cast list and sometimes the creditedAs
field in case where the onscreen credit was using a different name.
Example
{
"principalCastMembers": [
{
"billing": 1,
"category": "actor",
"creditedAs": "David Newman",
"nameId": "nm1453374",
"roles": ["Squeeze"]
},
...
]
}
principalCrewMembers
A short list of the most important crew credits for this title. This is always a subset of the crew from the creditsByCategory
list, but the selection and order is determined by IMDb. Also includes the category and job which qualified the credit for this list and sometimes the creditedAs
field in case where the onscreen credit was using a different name.
Example
{
"principalCrewMembers": [
{
"nameId": "nm0741627",
"category": "writer",
"job": "story"
},
...
]
}
certificates
A list of content rating certifications that have been given to a title, and the country where the rating applies or applied. For example a title may be given a 'PG-13' rating in the 'US' (by the MPAA). There may be additional attributes about the certificate or reasons for the rating provided by the rating organization (e.g. "Rated PG-13 for sequences of violence and action throughout").
Example
{
"certificates": [
{
"country": "US",
"rating": "R",
"ratingsBody": "MPAA",
"reason": "Rated R for language and prison violence"
},
...
]
}
color
Lists whether the title was filmed in black and white or color. Where titles include footage in both we list both, with the one that makes up the majority of the running time appearing first.
Example
{
"color": [
"Color",
"Black and White"
],
...
}
companies
Lists of the names of distribution, production, special-effects, and other miscellaneous companies associated with the making or subsequent distribution of this title. This list includes all companies that have ever been involved with the title, even if their involvement has now ended. These are ordered by on-screen credit order, or in the case of distribution companies by distribution release date.
distribution has the following attributes:
- "countries": list of countries.
- "startYear": the startYear of the credit.
- "endYear": the endYear of the credit.
- "format": what format(s) are the credit for.
- "company": Name, id and country of company.
- "isUncredited": Boolean for whether the company is uncredited.
production has the following attributes:
- "company": Name, id and country of company.
- "isUncredited": Boolean for whether the company is uncredited.
miscellaneous and specialEffects have the following attributes:
- "company": Name, id and country of company.
Additional information about companies associated with titles can be found on IMDb help site.
Example
{
"companies": {
"distribution": [
{
"company": {
"country": "US",
"id": "co0226183",
"name": "Walt Disney Studios Motion Pictures"
},
"countries": ["US"],
"endYear": 2019,
"formats": ["theatrical"],
"isUncredited": false,
"startYear": 2019
},
...
],
"miscellaneous": [
{
"company": {
"country": "US",
"id": "co0746914",
"name": "4DX"
}
},
...
],
"production": [
{
"company": {
"country": "US",
"id": "co0051941",
"name": "Marvel Studios"
},
"isUncredited": false
},
...
],
"specialEffects": [
{
"company": {
"country": "GB",
"id": "co0454255",
"name": "Territory Studio"
}
},
...
]
}
}
countries
A list of ISO 3166 country codes for the countries in which the production companies for the title are based. For more details see IMDb help site.
episodeInfo
For titles that are episodes, this contains information about the series, such as the series title ID, season number and episode number. It also includes the season and episode numbers where relevant.
Example
{
"episodeInfo":
{
"seriesTitleId": "tt0944947",
"episodeNumber": 1,
"seasonNumber": 8
}
}
seriesInfo
For titles that are series, this contains additional information about the series, such as the year it started airing, the year it finished airing (if it has finished), and a list of all the episode title IDs in the series ordered by episode number (e.g. season 1 episode 1, season 1 episode 2, etc.).
Example
{
"seriesInfo": {
"startYear": 2011,
"endYear": 2019,
"episodeTitleIds": [
"tt1480055",
"tt1668746",
"tt1829962",
...
]
}
}
episodeTitleIds
For titles which are series, the IMDb title IDs for all the episodes of that series.
officialSiteLinks
A list of URLs (and optionally their link titles) linking to this title's official website.
Example
{
"officialSiteLinks": [
{
"url": "www.example.com/official/example-title",
"linkTitle": "Example official website for title"
},
...
]
}
genres
A list of genres to which this title belongs. The full list of allowed genres and guidelines for how titles should be categorized can be found on IMDb help site. IMDb defines a limited list of genres but may add more in the future.
image
A URL linking to the primary image associated with this title, such as a movie poster or still frame. Additionally, includes the id and the width and height of the image in pixels.
Example
{
"image": {
"height": 1500,
"id": "rm2927108352",
"url": "https://m.media-amazon.com/images/M/MV5BMWU4N2FjNzYtNTVkNC00NzQ0LTg0MjAtYTJlMjFhNGUxZDFmXkEyXkFqcGdeQXVyNjc1NTYyMjg@._V1_.jpg",
"width": 974
}
}
imdbUrl
The IMDb URL in which the name or title is visible on www.imdb.com
.
isAdult
Whether or not this title contains adult content. Useful if you would like to filter out all adult content from your copy of the data set.
keywords
A keyword is a word (or group of connected words) attached to a title (movie / TV series / TV episode) to describe any notable object, concept, style or action that takes place during a title. A keyword can be a single word (e.g. waterfall) or a phrase with words separated by space (e.g. world war two; running away from home).
keywords is a list of keywords associated with the title, sorted most relevant first as voted on by IMDb customers. keywords has the following attributes for each keyword:
category
: Contains the category the keyword belongs to. For more information on categorization, see the note below.keyword
: Contains the keyword itself.votes
: Contains the number of up votes and down votes IMDb customers have given this keyword when rating it for helpfulness.
Current Keyword Categories (more may be added in the future):
adult-only
: Keywords which depict adult-themes or sexually-explicit phrases.character
: Keywords that show that this title contains a well known character that may appear in many titles. These keywords most of the time have a ʻcharacterʼ suffix.other
: Used to capture any keywords that do not fit into the above categories (e.g. directed by woman; f rated).plot-detail
: Keywords describing elements of the plot of this title. (e.g. humanity in jeopardy; metaverse).plot-timeframe
: Used to specify what timeframe the title's plot is set in (e.g. 1980s; 20th century).potentially-offensive
: Keywords that may be offensive or inoffensive depending on the context of the title.subgenre
: Used to specify which subgenres apply to the title (e.g. romantic-comedy; musical-comedy).title-description
: Keywords which describe the title itself, rather than any elements of the plot or content of the title (e.g. "based on comic strip"; "sequel").
More information about keywords and guidance for how they are associated with at title can be found on the IMDb help site.
Example
{
"keywords": [
{
"category": "plot-detail",
"keyword": "dream",
"votes": {
"up": 5,
"down": 7
}
},
...
]
}
languages
A list of ISO 639 language codes for the languages spoken in this title, in order of frequency that they are spoken in the title. For more details see IMDb help site.
locations
A list of locations where scenes from this title were filmed and optionally names or descriptions of the scenes which used that location.
Example
{
"locations": [
{
"scenes": ["studio"],
"place": "Fox Movietone Studio, New York, USA"
},
...
]
}
movieConnections
A list of IMDb title IDs of other titles which have a connection to this title, and the type of connection, for example titles which reference or spoof this title. Optionally may include a description of the connection. A complete list of current connection types can be found on IMDb help site, although more may be added in future.
Example
{
"movieConnections": [
{
"type": "referenced_in",
"titleId": "tt2336547",
"text": "Jack criticizes the film for depicting 11 Americans being swayed by Jane Fonda's father"
},
...
]
}
plot
A plot description of this title. It will take the value of plotShort
if available, or plotMedium
if plotShort
is not present. If neither exists, the plot
will be empty.
plotShort
The plot outline of the title if available. It never contains spoilers and its maximum length is 239 characters.
plotMedium
The plot summary of the title if available. Most plot summaries are reasonably brief, a paragraph or two normally. If there are multiple plot summaries available for this title on IMDb.com, then the one provided here will have been selected to display prominently on the title's main page by our users or manual vetting team.
plotLong
The synopsis of this title if available. A long, detailed description of the entire plot of the title. It may contain spoilers.
releaseDates
A list of the release dates (ISO 8601 date format) for this title, together with the country (an ISO 3166 country code) to which each release date applies.
Note that each release date may specify year, month and day (e.g. 1979-08-16
), year and month (e.g. 1979-08
) or only year (e.g. 1979
).
Example
{
"releaseDates": [
{
"date": "1957-04",
"country": "GB"
},
{
"date": "1957-04-10",
"country": "US"
},
{
"date": "2016-02-24",
"country": "CZ"
},
...
]
}
productionStatus
A list of production statuses for this title in ascending order by date, with the last status being the current production status. The available statuses for in-production listings are available on IMDb help site.
{
"productionStatus": [
...
{
"updated": "2008-12-02",
"status": "pre production"
},
{
"updated": "2009-10-24",
"status": "filming"
},
{
"updated": "2011-04-17",
"status": "released"
}
]
}
runtimeMinutes
The running time of this title in minutes.
taglines
A list of taglines for this title. A tagline is a short description or comment on a title that is often displayed on posters. For additional details see IMDb help site.
titleType
The type of this title, e.g. 'movie' or 'episode'.
imdbRating
The IMDb Rating for the title. The rating is between 1 and 10 and given to one decimal place. See IMDb help site for more information on how the rating is calculated. We also include the number of IMDb users who have voted on this title. A single IMDb user can cast a maximum of one vote. This field can be missing from an entry when we do not yet have an IMDb rating for the title in question. This can occur either because it does not yet have enough votes, or it has not yet been released. A TV series rating is not the weighted average of the ratings of individual episodes. Instead, customers vote separately for the rating of the series as a whole via each title’s series page.
Example
{
"rating": 8.9,
"numberOfVotes": 613399
}
year
The year of the earliest release of this title globally.
trivia
Contains a list of up to 10 of the most interesting trivia related to a title, contributed by IMDb customers, ordered with most interesting first based on customer votes on IMDb.com.
Each trivia item includes an interest score (showing the number of IMDb customers who voted the trivia as interesting, against the total number who voted), a spoiler flag, and the category of trivia type (for example but not limited to; actor-trademark, cameo, “director-cameo”, “director-trademark”, “smithee”). Trivia which do not have a trivia type will have category as "Uncategorized". All trivia items are currently in English.
For more information on IMDb Trivia see IMDb help pages.
Example
{
"titleId": "tt0068646",
"trivia": [
{
"interestScore": {
"usersInterested": 21,
"usersVoted": 14
},
"isSpoiler": false,
"category": "Cameo",
"text": "The film's associate producer as the cowboy in the studio when Tom Hagen encounters Studio Head Woltz for the first time."
},
...
]
}
goofs
Contains a list of up to 10 of the most interesting goofs (unintentional errors) related to a title, contributed by IMDb customers, ordered with most interesting first based on customer votes on IMDb.com.
Each goof item includes an interest score (showing the number of IMDb customers who voted the goof as interesting, against the total number who voted), a spoiler flag, and the category of goof type (for example but not limited to; “Anachronisms”, “Continuity”, “Factual errors”, “Character Errors”, “Plot hole”). All goof items are currently in English.
For more information on IMDb Goofs, including a full list of goof categories, see IMDb help pages.
Example
{
"titleId": "tt0167260",
"goofs": [
{
"interestScore": {
"usersInterested": 989,
"usersVoted": 1223
},
"isSpoiler": true,
"category": "Continuity",
"text": "In the scene of Theoden's death, a black line appears and disappears between shots on the right side of Eowyn's forehead, over her eyebrow."
}
]
}
parentsGuide
While IMDb also includes MPA and Certification ratings from around the world, Parents Guide gives parents, guardians and audiences additional information about the title that cannot be fully conveyed by certificates, since the beliefs that parents and guardians want to instill in their children can vary greatly.
parentsGuide lists the severity of content across each category; “Alcohol, Drugs & Smoking”, “Frightening & Intense Scenes”, “Profanity”, “Sex & Nudity”, “Violence & Gore” (sorted alphabetically). Severity is rated from “None”, through “Mild”, “Moderate”, and “Severe” along with the number of customers who have voted for each severity.
More information on IMDb Parents Guide along with our guidelines for contributions can be found on IMDb help pages.
Example
{
"parentsGuide":[
{
"category": "Profanity",
"severity": "Mild",
"votes": {
"noneVotes": 40,
"mildVotes": 136,
"moderateVotes": 35,
"severeVotes": 4
}
},
{
"category": "Violence & Gore",
"severity": "Severe",
"votes": {
"noneVotes": 2,
"mildVotes": 12,
"moderateVotes": 39,
"severeVotes": 114
}
},
...
]
}
A full list of documentation for each IMDb box office field as well as a key for international area rolls up codes.