IMDb Data Key Concepts

Fresh

Before working with the IMDb API or Bulk Data, understanding how IMDb identifies and manages entities is essential. These concepts apply across both the GraphQL API and all bulk data products.

IMDb IDs

Every entity in the IMDb database — titles, names, and companies — has a unique, permanent identifier called an IMDb ID. IDs follow a consistent format:

• A 2-letter prefix that identifies the type of entity
• A 7 or more digit number (zero-padded to at least 7 digits)

Prefix Reference

Prefix	Entity Type	Example
tt	Titles (movies, TV shows, video games)	tt0050083
nm	Names (people: actors, directors, writers)	nm0000020
co	Companies (production, distribution)	co0071326

Common Examples

IMDb ID	Entity
tt0050083	12 Angry Men (1957)
tt0133093	The Matrix (1999)
tt0120338	Titanic (1997)
tt0068646	The Godfather (1972)
nm0000020	Henry Fonda
nm0000151	Morgan Freeman
nm0000229	Steven Spielberg

---

Duplicate IDs (Remapping)

IMDb occasionally identifies that two separate entries in its database represent the same real-world entity. When this happens, one ID is designated as the canonical ID and the other is remapped to it.

How Remapping Works

• The remapped ID is retired as an active record
• The remappedTo field on the old ID points to the canonical ID
• The canonicalId field confirms the authoritative record
• Both IDs remain permanently in the system but only the canonical ID has full data

In the GraphQL API

When querying a remapped title or name, the API response includes a remappedTo field with the canonical ID. Your application should follow these remappings to ensure it is working with current data.

In Bulk Data

Bulk data records for remapped entities will contain the remappedTo field. When processing bulk data at scale, always check for this field and redirect your processing to the canonical record.

{
  "titleId": "tt9999999",
  "remappedTo": "tt0050083",
  "originalTitle": "12 Angry Men"
}

---

Deleted IDs

IMDb IDs are never reassigned to a different entity. If an ID is deleted — because the entry was determined to be a duplicate or an error — the ID is retired permanently. A deleted ID will never be given to a new movie, person, or company. This guarantees that any external system storing IMDb IDs will never encounter an ID collision.

---

Principal Credits

IMDb maintains a curated set of credits for each title called Principal Credits. These represent the most important cast and crew contributions according to IMDb's editorial standards — not a complete list of every person who worked on a production.

Key Points

• Principal credits are a subset of the full credits for a title
• They are chosen by IMDb's editorial team based on the significance of the contribution
• They include both cast (actors) and crew (directors, writers, producers, etc.)
• The principalCastMembers and principalCrewMembers fields in bulk data reflect this curated set

Why Principal Credits Matter

When building applications that display credits for a title, principal credits offer a clean, editorially curated list that is suitable for display without overwhelming users with hundreds of minor contributions. Full credits are available through the GraphQL API's credits field with category filtering.

---

IMDb URL Format

When linking from your application to IMDb pages, the standard URL format uses the IMDb ID:

• Title: https://www.imdb.com/title/{titleId}/
• Name: https://www.imdb.com/name/{nameId}/

The imdbUrl field in bulk data records provides the full URL for each entity.

Ref Markers

IMDb uses refmarker parameters in URLs to track the source of traffic. The format is ?ref_=xx_xxx_x. When building attribution links, include an appropriate ref marker if you have one assigned to your integration.