Skip to content

Latest commit

 

History

History
94 lines (70 loc) · 2.49 KB

API.md

File metadata and controls

94 lines (70 loc) · 2.49 KB

API

Named Routes

For a better user experience, we provide clean URLs for popular lists:

  • / - Marvel Cinematic Universe (default)
  • /star-wars - Star Wars countdown
  • /dc - DC Universe countdown
  • /batman - Matt Reeves' Batman Universe countdown

These render HTML pages and can be used with the ?date= parameter.

Important Notes:

  • Named routes do NOT accept list_id query parameter - they always use their predefined list
  • Named routes return HTML only - for JSON, use /api?list_id=X

GET /api

Returns a JSON object detailing the next production from a TMDB list (defaults to MCU).

Query Parameters

  • date (optional): ISO formatted date (YYYY-MM-DD) to find the next production after this date. Defaults to today.
  • list_id (optional): TMDB list ID to query. Defaults to the MCU list (140624). This allows you to use this API as a wrapper for any TMDB list!

Response

{
    "id": 12345,
    "days_until": 100,
    "overview": "Text Description",
    "poster_url": "https://image.tmdb.org/t/p/w500/path/to/poster.jpg",
    "release_date": "2020-05-01",
    "title": "MCU Film Title",
    "type": "TV Show | Movie",
    "following_production": {
        "id": 67890,
        "days_until": 200,
        "overview": "Next production description",
        "poster_url": "https://image.tmdb.org/t/p/w500/path/to/next_poster.jpg",
        "release_date": "2020-08-01",
        "title": "Next MCU Production",
        "type": "Movie"
    }
}

Examples

Get next MCU production (default)

GET /api

Get next production after a specific date

GET /api?date=2020-11-01

Use a custom TMDB list

GET /api?list_id=12345

Try these custom lists for Star Wars and more

GET /api?list_id=8563040  # Star Wars
GET /api?list_id=8563041  # DC Universe
GET /api?list_id=8563043  # Matt Reeves' Batman Universe

Combine date and custom list

GET /api?date=2025-01-01&list_id=12345

Validating TMDB Lists

To check if a TMDB list exists and see its contents, visit the list directly on TMDB:

https://www.themoviedb.org/list/YOUR_LIST_ID

For example, the MCU list: https://www.themoviedb.org/list/140624

Caching

All endpoints include cache headers (Cache-Control: public, max-age=3600) to reduce lambda costs and improve performance. The API caches TMDB responses in-memory for 1 hour by default.

Rate Limiting

This API is subject to TMDB's rate limits. Caching helps reduce the number of requests to TMDB.