Back to Blog

Solving the Anime Multi-Season Problem: Compact MAL-to-TMDB Offset Mapping

•Emmanouil Athanasopoulos•2 min read•320 words
Node.jsMedia TrackerAPI MappingData PipelineGitHub Actions

The Motivation Behind the Project

A notorious headache in building media tracking applications is the structural mismatch between Western and Japanese media databases. MyAnimeList assigns a brand new ID to every sequel, OVA, and film (e.g. Cardcaptor Sakura Season 2 is a separate MAL entry), whereas TMDB groups everything into a single TV show ID with multiple seasons and continuous episode numbering. To power seamless scrobbling in Media Tracker, I developed an automated daily pipeline that maps individual MAL IDs to exact TMDB series IDs, season numbers, and absolute episode start offsets.

Core Features and Design Goals

  • Season & Episode Offset Resolution: Maps individual MAL entries into precise TMDB show IDs, season numbers, and episode offsets (e.g. MAL 527 -> TMDB 46298 Season 2 Episode 79).
  • Persistent Metadata Cache: Maintains a committed anime-cache.json storing English/Romaji titles and posters to eliminate redundant API queries.
  • Automatic New Entry Enrichment: Queries Jikan and Kitsu for newly listed seasonal anime without manual intervention.
  • Compact Single-File Payload: Compiles into a single minified mal-tmdb-mapping.json consumed by mobile clients in one lightweight HTTP request.

Deep Dive: How It Works Under the Hood

When a user marks episode 12 of a sequel on MyAnimeList, tracking apps that consume TMDB need to translate that into Season 2, Episode 91. The mapping pipeline calculates these offset anchors by analyzing canonical Japanese broadcast schedules and matching them with TMDB's season episode partitions. The persistent cache ensures that daily CI jobs complete in seconds rather than hitting API rate limits on 40,000 entries.

Technical Implementation

  • Designed mathematical episode offset calculation translating MAL episode counts to TMDB season numbers.
  • Built persistent cache mechanism updating only newly discovered media entries.
  • Configured daily automated cron publishing to GitHub CDN.

The Technology Stack

Node.js, Jikan API, Kitsu API, and GitHub Actions.

Final Reflections

Data normalization between conflicting domain models is best solved at the pipeline level so client-side mobile apps can remain fast, responsive, and lightweight.