id-mapping-api/malid

🧠 ID Mapping API

 

An advanced ID mapping engine designed to bridge the gap between western metadata (IMDb/Cinemeta) and Japanese anime tracking (MyAnimeList). This API ensures perfect synchronization even for complex, split-season anime by relying on absolute release dates.

📖 Live Documentation

Interactive API documentation (Swagger UI) is available live. You can explore endpoints, view response schemas, and test queries directly from your browser:

👉 [View Interactive API Docs](https://id-mapping-api-malid.hf.space/)

🚀 Key Features

• —📅 Date-Based Fingerprinting: Matches episodes using absolute air dates rather than fragile season/episode numbers. This allows seamless mapping of "Part 2", "The Final Season", and split-cour releases.
• —🔍 Multi-Source Discovery: Automatically builds candidate lists by querying external services and performing intelligent title searches.
• —🕵️‍♂️ Total Stealth Mode: Routes MyAnimeList (Jikan) traffic through a Cloudflare Shield to bypass IP blocks and rate limits.
• —⚡ Enterprise-Grade Caching:
• —Level 1 (Instant): Full mapping results are cached in Supabase for sub-second repeat lookups.
• —Level 2 (Discovery): Whole anime episode lists are cached to allow instant cross-episode resolution within the same series.
• —🌍 Timezone-Proof: Implements a 2-day date tolerance with UTC-only string comparisons to handle global release discrepancies.

⚡ Powered By (Acknowledgments)

This project relies on fantastic community APIs to fetch metadata and map candidates. Huge thanks to:

• —[ARM (Anime Release Metadata)](https://github.com/haglund/arm): Used as the primary discovery network (arm.haglund.dev) to fetch a broad list of candidate MyAnimeList IDs from IMDb, TMDB, and TVDB identifiers.
• —[AniZip](https://github.com/ebakan/anizip): Used as a highly reliable fallback (api.ani.zip/mappings) for episode air dates when primary sources are missing data, ensuring flawless mapping for the latest seasons.
• —[Jikan](https://jikan.moe/): The Unofficial MyAnimeList API used for title searching and episode list retrieval.

🛠 API Usage

Resolve Episode Mapping

Resolves a Cinemeta/IMDb episode ID to its MyAnimeList equivalent.

Endpoint: GET /api/resolve

Query Parameters:

• —id: The IMDb series ID (e.g., tt2560140)
• —s: The season number (as seen in Cinemeta)
• —e: The episode number (as seen in Cinemeta)

Example Request:

curl "https://id-mapping-api-malid.hf.space/api/resolve?id=tt2560140&s=4&e=29"

Example Response:

{
    "id": "tt2560140:s4:e29",
    "imdb_id": "tt2560140",
    "season": 4,
    "episode": 29,
    "mal_id": 51535,
    "mal_episode": 1,
    "anime_title": "Attack on Titan",
    "air_date": "2023-03-03"
}

🏗 Setup & Installation

Environment Variables

You must configure the following environment variables:

Local Development

# Install dependencies
npm install

# Start the server
node server.js

🧩 How it Works: The "Truth" Algorithm

Traditional mapping fails when one database numbers an episode as S4 E29 and another calls it Part 3 Ep 1. This API solves the problem by:

1. 1.Extracting the "Fingerprint": Finding the exact release date of the requested episode from Cinemeta.
2. 2.Building the Net: Collecting candidate MyAnimeList IDs associated with the show via ARM and Jikan Search.
3. 3.The Matching Loop: Scanning the episode list of every candidate to find the episode that "was born" on that same day (falling back to AniZip if needed).
4. 4.DayIndex Resolution: If two episodes dropped on the same day (Specials), it uses their relative position to break the tie.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.

Maintained by [paregi12](https://github.com/paregi12)