MovieAPI Dokumentation

Vollständige Entwickler-Dokumentation für die MovieAPI. Diese API liefert Daten zu Filmen, Serien, Franchises und Personen – angereichert mit umfangreichen TMDb-Daten.

Einführung

Alle API-Endpunkte sind unter /api/v1/ erreichbar. Die API ist RESTful und gibt JSON zurück. Bilder werden als Base64 gespeichert und können als PNG-Bild abgerufen werden.

Rate Limiting: 15 Anfragen pro 30 Sekunden pro IP-Adresse.

Authentifizierung

Die API ist derzeit ohne Authentifizierung zugänglich (GET-Endpunkte). POST-Endpunkte (z.B. Franchise erstellen) erfordern keinen Token, sollten aber in Produktion durch einen Reverse-Proxy oder Firewall-Regel abgesichert werden.

TMDb-Integration

Alle Filme und Serien werden automatisch mit TMDb-Daten angereichert. Diese sind im Feld tmdbData gespeichert und enthalten alle wichtigen Informationen aus der TMDb API.

Die Anreicherung erfolgt beim ersten Hinzufügen eines Eintrags durch den Worker (alle 10 Minuten). Der API-Key kann via Umgebungsvariable TMDB_API_KEY gesetzt werden.

Filme & Serien

Alle Einträge abrufen

Film/Serie nach ID abrufen

Gibt einen einzelnen Eintrag zurück. Unterstützt dieselben Query-Parameter wie die Listenansicht.

Poster abrufen

Gibt das Poster als PNG-Bild zurück (Binary, Content-Type: image/png).

Cast/Crew abrufen

Franchises

Alle Franchises abrufen

Franchise erstellen

Erstellt eine neue Franchise. Das Bild wird automatisch heruntergeladen und als Base64 gespeichert.

{
  "name": "DC Universe",
  "imageUrl": "https://example.com/dc-logo.png"
}

Franchise-Bild abrufen

Filme einer Franchise abrufen

Personen

Datenmodell – Basis-Felder

Jeder Eintrag enthält folgende Top-Level-Felder (unabhängig von TMDb oder Franchise).

Franchise-spezifische Felder (franchiseSpecific)

Das franchiseSpecific-Objekt enthält Felder, die von der jeweiligen Datenquelle geliefert werden. Welche Felder befüllt sind, hängt vom origin-Wert ab.

Marvel – origin: "mcuapi"

Filme (type: "movie")

Serien (type: "series")

Beispiel

{
  "franchiseSpecific": {
    "saga": "The Infinity Saga",
    "phase": 1,
    "chronology": 2,
    "postCreditScenes": 1
  }
}

Star Wars – origin: "swapi"

Nur Filme (alle 9 Episoden). Star Wars hat keine Serien-Einträge in der SWAPI.

Beispiel

{
  "franchiseSpecific": {
    "episodeId": 4,
    "saga": "Original Trilogy",
    "director": "George Lucas",
    "producer": "Gary Kurtz, Rick McCallum",
    "openingCrawl": "It is a period of civil war.\nRebel spaceships..."
  }
}

Harry Potter – origin: "hpapi"

11 Filme: 8 Hauptreihe + 3 Fantastic Beasts Spinoffs.

Lord of the Rings – origin: "lotrapi"

6 Kinofilme: 3 LOTR + 3 Hobbit. Daten von The One API (optionaler LOTR_API_KEY).

Breaking Bad – origin: "breakingbadapi"

2 Serien (Breaking Bad, Better Call Saul) + 1 Film (El Camino). Episodenzahlen via Breaking Bad API.

Rick and Morty – origin: "rickandmortyapi"

1 Serien-Eintrag. Staffel- und Episodenzahlen werden live von der Rick and Morty API geladen.

DC Universe – origin: "dcuniverse"

17 DCEU-Filme + 1 DCEU-Serie + 2 DCU-Einträge (Gunn-Ära).

Game of Thrones – origin: "gameofthrones"

Game of Thrones (8 Staffeln) + House of the Dragon (Spinoff).

Pokémon – origin: "pokemon"

11 Animationsfilme + 1 Live-Action-Film + 2 Anime-Serien.

Avatar – origin: "avatar"

Avatar: The Last Airbender (Animated & Live-Action) + The Legend of Korra.

Serien-spezifische Felder (nur type: "series")

Zusätzliche Top-Level-Felder, die nur bei Serien vorhanden sind:

TMDb Film-Felder (movie.tmdbData)

Das Feld tmdbData enthält alle von TMDb geladenen Daten für einen Film.

TMDb Serien-Felder (serie.tmdbData)

Serien haben zusätzliche Felder (alles von oben plus):

Beispiel-Response

GET /api/v1/movies/1 (Film mit TMDb-Daten)

{
  "data": {
    "id": 1,
    "type": "movie",
    "franchiseId": 1,
    "name": "Iron Man",
    "year": 2008,
    "releaseDate": "2008-04-30",
    "ageRating": "12",
    "duration": 126,
    "genres": ["Action", "Abenteuer", "Science Fiction"],
    "description": "Der Rüstungsmilliardär Tony Stark wird bei einem Angriff...",
    "posterUrl": "https://image.tmdb.org/t/p/w500/...",
    "trailer": "https://www.youtube.com/watch?v=...",
    "imdbId": "tt0371746",
    "tmdbId": 1726,
    "tmdbData": {
      "tmdbId": 1726,
      "imdbId": "tt0371746",
      "title": "Iron Man",
      "originalTitle": "Iron Man",
      "originalLanguage": "en",
      "overview": "Der Rüstungsmilliardär Tony Stark...",
      "tagline": "Bereit für den Anzug?",
      "status": "Released",
      "releaseDate": "2008-04-30",
      "runtime": 126,
      "budget": 140000000,
      "revenue": 585366247,
      "popularity": 87.3,
      "voteAverage": 7.6,
      "voteCount": 24891,
      "adult": false,
      "genres": [
        { "id": 28, "name": "Action" },
        { "id": 12, "name": "Abenteuer" }
      ],
      "posterUrl": "https://image.tmdb.org/t/p/w500/78lPtwv72eTNqFW9COBYI0dWDJa.jpg",
      "backdropUrl": "https://image.tmdb.org/t/p/w1280/...",
      "images": {
        "posters": [ { "url": "...", "width": 2000, "height": 3000, "lang": "de" } ],
        "backdrops": [ { "url": "...", "width": 3840, "height": 2160, "lang": null } ]
      },
      "cast": [
        { "tmdbPersonId": 3223, "name": "Robert Downey Jr.", "character": "Tony Stark / Iron Man", "order": 0, "profileUrl": "https://image.tmdb.org/t/p/w185/..." },
        { "tmdbPersonId": 16483, "name": "Gwyneth Paltrow", "character": "Pepper Potts", "order": 1, "profileUrl": "..." }
      ],
      "crew": [
        { "tmdbPersonId": 17966, "name": "Jon Favreau", "job": "Director", "department": "Directing", "profileUrl": "..." },
        { "tmdbPersonId": 7624, "name": "Kevin Feige", "job": "Producer", "department": "Production", "profileUrl": "..." }
      ],
      "videos": [
        { "id": "533ec654c3a3685448000004", "name": "Offizieller Trailer", "type": "Trailer", "site": "YouTube", "key": "8ugaeA-nMTc", "url": "https://www.youtube.com/watch?v=8ugaeA-nMTc", "official": true }
      ],
      "trailerUrl": "https://www.youtube.com/watch?v=8ugaeA-nMTc",
      "watchProviders": {
        "link": "https://www.themoviedb.org/movie/1726/watch",
        "flatrate": [
          { "id": 337, "name": "Disney Plus", "logoUrl": "https://image.tmdb.org/t/p/w92/...", "displayPriority": 1 }
        ],
        "rent": [],
        "buy": [
          { "id": 10, "name": "Amazon Video", "logoUrl": "...", "displayPriority": 5 }
        ],
        "ads": []
      },
      "recommendations": [
        { "tmdbId": 1724, "title": "Der unglaubliche Hulk", "posterUrl": "...", "releaseDate": "2008-06-12", "voteAverage": 6.3 }
      ],
      "similar": [ ... ],
      "keywords": [
        { "id": 9715, "name": "Superheld" },
        { "id": 180547, "name": "Marvel Cinematic Universe" }
      ],
      "certification": "12",
      "externalIds": {
        "imdbId": "tt0371746",
        "wikidataId": "Q191875",
        "facebookId": "IronMan",
        "instagramId": null,
        "twitterId": null
      },
      "tmdbUrl": "https://www.themoviedb.org/movie/1726",
      "fetchedAt": "2025-01-15T12:00:00.000Z"
    }
  }
}

POST /api/v1/franchises

// Request:
{
  "name": "DC Universe",
  "imageUrl": "https://upload.wikimedia.org/wikipedia/commons/.../DC.png"
}

// Response (201 Created):
{
  "message": "Franchise erfolgreich erstellt",
  "data": {
    "id": 2,
    "name": "DC Universe"
  }
}

TMDb Attribution

Die Nutzung der TMDb API erfordert folgende Attributionen:

• Logo: TMDb Logo & Attributions
• Text: "This product uses the TMDB API but is not endorsed or certified by TMDB."
• Jede Response enthält das Feld tmdbData.tmdbUrl für den direkten Link zur TMDb-Seite.

Umgebungsvariablen