Skip to content

API.md

Latest commit

 

History

History
298 lines (238 loc) · 7.56 KB

API.md

File metadata and controls

298 lines (238 loc) · 7.56 KB

ReelDB API

Base URL: https://api.reeldb.io

All endpoints require an apikey query parameter.

Authentication

apikey=YOUR_KEY

Invalid, revoked, or unauthorized API keys return 403. Rate-limited requests return 429.

Search

GET /v1/search

Search movies and series. Results are paginated with 10 results per page.

Parameter Description
q Required. Search query, minimum 2 characters.
type Optional. movie or series.
y Optional. Release year filter.
page Optional. Page number. Defaults to 1. 
curl "https://api.reeldb.io/v1/search?q=matrix&apikey=YOUR_KEY"

Example response shape:

{
  "results": [
    {
      "ids": { "imdb": "tt0133093", "tmdb": 603, "mdblist": "the-matrix" },
      "title": "The Matrix",
      "year": 1999,
      "type": "movie",
      "poster": "https://image.tmdb.org/t/p/original/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg",
      "score": 82
    }
  ],
  "total": 8,
  "page": 1,
  "pages": 1
}

Title Lookup

GET /v1/title

Fetch full title metadata.

Parameter Description
imdb IMDb ID, such as tt0133093.
tmdb TMDb numeric ID, such as 603.
t Title text. Returns the best match.
type Optional. movie or series.
y Optional. Release year filter.
append Optional comma-separated extras: cast, providers, seasons.

Provide one of imdb, tmdb, or t.

curl "https://api.reeldb.io/v1/title?imdb=tt0133093&apikey=YOUR_KEY"
curl "https://api.reeldb.io/v1/title?tmdb=603&apikey=YOUR_KEY"
curl "https://api.reeldb.io/v1/title?t=The+Matrix&type=movie&apikey=YOUR_KEY"
curl "https://api.reeldb.io/v1/title?imdb=tt0133093&append=cast,providers&apikey=YOUR_KEY"

Example response shape:

{
  "ids": {
    "imdb": "tt0133093",
    "tmdb": 603,
    "tvdb": null,
    "trakt": 481,
    "mal": null,
    "mdblist": "the-matrix"
  },
  "title": "The Matrix",
  "original_title": "The Matrix",
  "year": 1999,
  "type": "movie",
  "certification": "R",
  "runtime": 136,
  "status": "Released",
  "released": "1999-03-31",
  "released_digital": null,
  "description": "Set in the 22nd century, The Matrix tells the story of a computer hacker who joins a group of underground insurgents fighting the vast and powerful computers who now rule the earth.",
  "poster": "https://image.tmdb.org/t/p/original/f89U3ADr1oiB1s9GkdPOEpXUk5H.jpg",
  "backdrop": "https://image.tmdb.org/t/p/original/fNG7i7RqMErkcqhohV2a6cV1Ehy.jpg",
  "trailer": "https://www.youtube.com/watch?v=vKQi3bBA1y8",
  "genres": ["Action", "Science Fiction"],
  "languages": [{ "code": "en", "name": "English" }],
  "countries": [{ "code": "US", "name": "United States of America" }],
  "ratings": {
    "imdb":              { "rating": 8.7, "votes": 2100000 },
    "metacritic":        { "rating": 73,  "votes": null },
    "metacritic_user":   { "rating": 8.3, "votes": 2800 },
    "trakt":             { "rating": 8.5, "votes": 45000 },
    "tomatoes":          { "rating": 83,  "votes": null, "certified_fresh": true },
    "tomatoes_audience": { "rating": 85,  "votes": 100000 },
    "tmdb":              { "rating": 8.2, "votes": 25000 },
    "letterboxd":        { "rating": 4.2, "votes": 1800000 },
    "roger_ebert":       { "rating": 3.5, "votes": null },
    "myanimelist":       null,
    "mdblist":           { "rating": 82,  "votes": null }
  },
  "production": {
    "budget": 63000000,
    "revenue": 463517383,
    "companies": [
      { "tmdb_id": 79, "name": "Village Roadshow Pictures", "country": "AU" }
    ]
  }
}

For TV series, the response also includes a series object:

{
  "series": {
    "total_seasons": 8,
    "total_runtime": 2856,
    "network": "HBO",
    "last_air_date": "2019-05-19",
    "next_air_date": null
  }
}

Path-Based Title IDs

Title subresource endpoints accept {id} in several formats:

ID format Meaning
tt0133093 IMDb ID (auto-detected)
603 TMDb ID (auto-detected for numeric values)
the-matrix MDBList public ID or slug

Use id_type=imdb|tmdb|trakt|tvdb|mal|mdblist to override auto-detection.

Ratings

GET /v1/title/{id}/ratings

Returns ratings from IMDb, Metacritic, Trakt, Rotten Tomatoes, TMDb, Letterboxd, Roger Ebert, MyAnimeList, and MDBList when available.

curl "https://api.reeldb.io/v1/title/tt0133093/ratings?apikey=YOUR_KEY"
curl "https://api.reeldb.io/v1/title/603/ratings?apikey=YOUR_KEY"

Response shape matches the ratings object from /v1/title.

Cast & Crew

GET /v1/title/{id}/cast

Returns directors, writers, actors, guests, role data, and profile images when available.

curl "https://api.reeldb.io/v1/title/tt0133093/cast?apikey=YOUR_KEY"

Example response shape:

{
  "directors": [
    { "tmdb_id": 9340, "name": "Lana Wachowski", "role": "Director", "profile": "https://image.tmdb.org/t/p/w185/..." }
  ],
  "writers": [
    { "tmdb_id": 9340, "name": "Lana Wachowski", "role": "Writer", "profile": "https://image.tmdb.org/t/p/w185/..." }
  ],
  "actors": [
    { "tmdb_id": 6384, "name": "Keanu Reeves", "role": "Neo", "profile": "https://image.tmdb.org/t/p/w185/..." }
  ],
  "guests": [],
  "counts": { "cast": 42, "crew": 18 }
}

Streaming Providers

GET /v1/title/{id}/providers

Returns streaming availability grouped by region and offer type when available.

curl "https://api.reeldb.io/v1/title/tt0133093/providers?apikey=YOUR_KEY"

Example response shape:

{
  "US": [
    { "provider_id": 8,   "provider_name": "Netflix",       "provider_type": 1, "provider_type_name": "flatrate" },
    { "provider_id": 2,   "provider_name": "Apple TV",      "provider_type": 3, "provider_type_name": "buy" },
    { "provider_id": 192, "provider_name": "YouTube",       "provider_type": 3, "provider_type_name": "buy" }
  ],
  "GB": [
    { "provider_id": 8,   "provider_name": "Netflix",       "provider_type": 1, "provider_type_name": "flatrate" }
  ]
}

Seasons

GET /v1/title/{id}/seasons

Returns all seasons for a series.

curl "https://api.reeldb.io/v1/title/tt0944947/seasons?apikey=YOUR_KEY"

Example response shape:

[
  {
    "season_number": 1,
    "name": "Season 1",
    "episode_count": 10,
    "air_date": "2011-04-17",
    "poster_path": "/zwaj4egrhnXOBIit1tyeQ9oUDy.jpg",
    "overview": "Trouble is brewing in the Seven Kingdoms of Westeros..."
  }
]

Season Detail

GET /v1/title/{id}/seasons/{season_number}

Returns season metadata and all episodes.

curl "https://api.reeldb.io/v1/title/tt0944947/seasons/1?apikey=YOUR_KEY"

Example response shape:

{
  "season_number": 1,
  "name": "Season 1",
  "overview": "Trouble is brewing in the Seven Kingdoms of Westeros...",
  "air_date": "2011-04-17",
  "episode_count": 10,
  "poster_path": "/zwaj4egrhnXOBIit1tyeQ9oUDy.jpg",
  "series": { "imdb_id": "tt0944947", "title": "Game of Thrones" },
  "episodes": [
    {
      "episode_number": 1,
      "name": "Winter Is Coming",
      "overview": "Jon Arryn, the Hand of the King, is dead...",
      "air_date": "2011-04-17",
      "runtime": 62,
      "vote_average": 9.0,
      "vote_count": 5200,
      "still_path": "/xIfXit6BpMx3gNGiLqQKvJDJfPE.jpg"
    }
  ]
}

Errors

JSON endpoints return errors as:

{
  "error": "Title not found"
}

Common status codes:

Status Meaning
400 Invalid request parameters.
403 Invalid API key or endpoint not allowed for the key.
404 Title, season, or episode not found.
429 Daily or per-minute rate limit exceeded.
500 Server error.