Bulk Data Key Concepts

Fresh

JSON Lines Format

All IMDb bulk data files use the JSON Lines format (also called NDJSON — Newline Delimited JSON). This format has three characteristics:

1. UTF-8 encoded — All files are encoded in UTF-8
2. Each line is valid JSON — Every line in a file can be independently parsed as a complete JSON object
3. One entity per IMDb ID — Each line represents a single record (one title, one name, one box office entry, etc.)

Example

{"titleId":"tt0050083","originalTitle":"12 Angry Men","titleType":"movie","year":1957}
{"titleId":"tt0068646","originalTitle":"The Godfather","titleType":"movie","year":1972}
{"titleId":"tt0133093","originalTitle":"The Matrix","titleType":"movie","year":1999}

This format makes bulk data easy to process line by line in streaming fashion, even for files with millions of records, without loading the entire file into memory.

---

Versioning

Bulk data schemas use a version number included in the filename. For example: title_essential_v2 or geo_star_meter_v1.

Non-Breaking Changes

Schema updates that are backward-compatible are not accompanied by a version number change. These include:

• Adding new optional fields
• Adding new values to an existing enumeration
• Adding new nested object keys

Your application should be built to tolerate unexpected keys in the JSON objects it processes.

Breaking Changes

A version number increment (e.g., from v1 to v2) signals a breaking change. These include:

• Removing existing fields
• Renaming existing fields
• Changing the data type of an existing field
• Restructuring nested objects in an incompatible way

When a version number changes, you must update your processing code and any Athena DDL table definitions before consuming the new version.

---

Data Structure Conventions

IMDb bulk data follows consistent conventions for handling missing or empty data:

• No null values — A field that would be null is simply omitted from the JSON object
• No empty objects — An object with no populated fields is omitted entirely
• No empty arrays — An array with zero elements is omitted

This means your code should use optional field access (checking for key existence) rather than expecting null values. In Python, use .get(). In TypeScript, use optional chaining (?.).

Example

A title with no awards data:

{
  "titleId": "tt0050083",
  "originalTitle": "12 Angry Men",
  "titleType": "movie",
  "year": 1957
}

The same schema for a title with awards data:

{
  "titleId": "tt0068646",
  "originalTitle": "The Godfather",
  "titleType": "movie",
  "year": 1972,
  "awards": [
    {
      "year": 1973,
      "awardName": "Academy Awards",
      "category": "Best Picture",
      "winner": true,
      "event": "Oscars"
    }
  ]
}

The awards key is only present when the title has award data. Code that expects awards to always exist will encounter key errors.

---

Data Consistency Model

IMDb bulk data uses an eventually consistent distribution model:

• Changes to IMDb data (edits, new submissions, corrections) propagate through the system in seconds to minutes
• The bulk data files are updated daily and reflect the state of the database at the time the snapshot was generated
• In rare cases, a temporary inconsistency may appear within a single revision, where a field in one entity references an ID that does not yet appear in its corresponding entity file

These temporary inconsistencies resolve automatically in the next daily revision. Build your processing logic to handle missing cross-references gracefully rather than treating them as errors.

---

Linking to IMDb

When building applications that display IMDb data and want to link users back to the IMDb website, use the following URL formats:

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

The imdbUrl field in bulk data records provides the pre-formatted URL for each entity.

Ref Markers

If your integration has been assigned a ref marker by IMDb, append it to your links:

https://www.imdb.com/title/tt0068646/?ref_=your_ref_marker

The format is ?ref_=xx_xxx_x. Contact imdb-licensing@imdb.com if you need a ref marker assigned to your application.