TOP Posters API - Developer Documentation

📚 Interactive Docs

Explore all endpoints with Swagger UI. Test calls directly from your browser and see real-time responses.

Open Swagger UI

📖 ReDoc

Alternative documentation view with a clean, easy-to-navigate interface — great for reading the full API reference.

Open ReDoc

📋 Changelog

Latest updates, new features, and improvements to the API. Check here before integrating to stay up to date.

View Changelog

✨ Key Features

🎨 20+ Rating Sources

IMDb, Rotten Tomatoes, Metacritic, Letterboxd, Trakt, MAL, TMDb, AlloCiné and more in a single poster

📊 Trend Badges

Visual popularity indicators (↑ up, ↓ down, new, stable) — customizable per user

🌍 35+ Languages

Localized posters in EN, IT, ES, FR, DE, PT and many more (Pro/Premium)

⚡ Intelligent Cache

LRU cache system for ultra-fast repeated requests

🖼️ Episode Thumbnails

Episode thumbnails with episode-specific rating overlay (Premium only)

🔌 RPDB Compatible

Drop-in replacement for RatingPosterDB — works with Jellyfin, Plex and Emby

🚀 Quick Start

Get started right away. Replace YOUR_API_KEY with your key — register at /user/register to get one for free.

Python

# pip install requests
import requests

API_KEY = "YOUR_API_KEY"

# Poster by IMDb ID
url = f"http://api.top-posters.com/{API_KEY}/imdb/poster/tt0111161.jpg"
response = requests.get(url)

# Poster by TMDB ID with Italian language and trend
url = f"http://api.top-posters.com/{API_KEY}/tmdb/poster/movie-550.jpg"
response = requests.get(url, params={"lang": "it-IT", "trend": "up:5"})

if response.status_code == 200:
    with open("poster.jpg", "wb") as f:
        f.write(response.content)
    print("Poster saved!")
            

JavaScript

const API_KEY = "YOUR_API_KEY";

// Poster by IMDb ID
const url = `http://api.top-posters.com/${API_KEY}/imdb/poster/tt0111161.jpg`;

fetch(url)
  .then(res => res.blob())
  .then(blob => {
    const img = document.getElementById('poster');
    img.src = URL.createObjectURL(blob);
  });

// Episode thumbnail (Premium)
const thumbUrl = `http://api.top-posters.com/${API_KEY}/imdb/thumbnail/tt0903747/S1E1.jpg`;
            

cURL

# Poster
curl -o poster.jpg \
  "http://api.top-posters.com/YOUR_API_KEY/imdb/poster/tt0111161.jpg?lang=it-IT&trend=up:5"

# Episode thumbnail (Premium)
curl -o thumb.jpg \
  "http://api.top-posters.com/YOUR_API_KEY/imdb/thumbnail/tt0903747/S1E1.jpg"
            