# Movie details API > The movie details endpoint returns one movie by id at GET /3/movie/{movie_id}. The JSON matches TMDB v3, so existing clients only need a new base URL. Add append_to_response to fetch credits, videos, images and the amodb extras ratings, moods, soundtracks, wikidata and showtimes in one request. ## Endpoint `GET /3/movie/{movie_id}` ```bash curl "https://api.amodb.dev/3/movie/550?language=en-US" \ -H "Authorization: Bearer $AMODB_KEY" ``` Response: ```json { "adult": false, "backdrop_path": "/b9HyPoxwxjxkWEUL5ErZdhApQe2.jpg", "belongs_to_collection": null, "budget": 63000000, "genres": [ { "id": 18, "name": "Drama" }, { "id": 53, "name": "Thriller" } ], "homepage": "https://www.20thcenturystudios.com/movies/fight-club", "id": 550, "imdb_id": "tt0137523", "origin_country": [ "US", "DE" ], "original_language": "en", "original_title": "Fight Club", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking new form of therapy. Their concept catches on, with underground \"fight clubs\" forming in every town, until an eccentric gets in the wa...", "popularity": 39.0054, "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg", "production_companies": [ { "id": 25, "logo_path": "/nM2MfoMqzJQRiSynsDabOtFKetD.png", "name": "20th Century Fox", "origin_country": "US" }, { "id": 508, "logo_path": "/4sGWXoboEkWPphI6es6rTmqkCBh.png", "name": "Regency Enterprises", "origin_country": "US" }, { "id": 711, "logo_path": "/tEiIH5QesdheJmDAqQwvtN60727.png", "name": "Fox 2000 Pictures", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" }, { "iso_3166_1": "DE", "name": "Germany" } ], "release_date": "1999-10-15", "revenue": 101209702, "runtime": 139, "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" } ], "status": "Released", "tagline": "Mischief. Mayhem. Soap.", "title": "Fight Club", "video": false, "vote_average": 8.437, "vote_count": 33042 } ``` ## Get movie details `GET /3/movie/{movie_id}` returns the core record for one movie: titles, overview, runtime, genres, release date, budget, revenue, production companies and image paths. The id is the same numeric id TMDB uses, so a movie you already store as `550` keeps that id here. The example below asks for the movie in English and appends its ratings in the same call. ```bash curl -s "https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings" \ -H "Authorization: Bearer $AMODB_KEY" ``` ```js const url = 'https://api.amodb.dev/3/movie/550?language=en-US&append_to_response=ratings'; const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AMODB_KEY}` } }); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const movie = await res.json(); console.log(movie.title, movie.runtime, movie.ratings.imdb?.value); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/3/movie/550", params={"language": "en-US", "append_to_response": "ratings"}, headers={"Authorization": f"Bearer {os.environ['AMODB_KEY']}"}, timeout=10, ) r.raise_for_status() movie = r.json() imdb = movie["ratings"]["imdb"] print(movie["title"], movie["runtime"], imdb and imdb["value"]) ``` ```php true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AMODB_KEY')], ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $movie = json_decode($body, true); echo $movie['title'], ' ', $movie['runtime'], ' ', $movie['ratings']['imdb']['value'] ?? 'n/a', PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "os" ) type Movie struct { Title string `json:"title"` Runtime int `json:"runtime"` } func main() { url := "https://api.amodb.dev/3/movie/550?language=en-US" req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+os.Getenv("AMODB_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var m Movie json.NewDecoder(res.Body).Decode(&m) fmt.Println(m.Title, m.Runtime) } ``` ### Parameters | Parameter | In | Required | Description | | -------------------- | ----- | ---------- | -------------------------------------------------------------------------------------------- | | `movie_id` | path | yes | Numeric movie id, for example `550`. | | `api_key` | query | one of two | Your key. Use this or the `Authorization: Bearer` header. | | `language` | query | no | TMDB tag such as `en-US`, `ru-RU` or `pt-BR`. 14 base languages are served. Default `en-US`. | | `append_to_response` | query | no | Comma separated list of up to 20 sub-resources to merge into the reply. | ### Response fields | Field | Type | Notes | | ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------ | | `id` | integer | Movie id. | | `imdb_id` | string or null | IMDb id such as `tt0137523`. | | `title`, `original_title` | string | Localized and original title. | | `original_language` | string | Language code such as `en`. | | `overview`, `tagline` | string | Localized text, empty when no translation exists. | | `homepage` | string | Official site, empty when unknown. | | `release_date` | string | `YYYY-MM-DD`, empty when unknown. | | `status` | string | Release state, for example `Released` or `In Production`. | | `runtime` | integer | Minutes. | | `budget`, `revenue` | integer | US dollars, `0` when unknown. | | `genres` | array | Objects with `id` and `name`. | | `belongs_to_collection` | object or null | `id`, `name`, `poster_path`, `backdrop_path`. See [collections](https://amodb.dev/collections/). | | `production_companies` | array | `id`, `logo_path`, `name`, `origin_country`. | | `production_countries` | array | `iso_3166_1`, `name`. | | `spoken_languages` | array | `english_name`, `iso_639_1`, `name`. | | `origin_country` | array | Country codes such as `US`. | | `poster_path`, `backdrop_path` | string or null | Append to `https://img.amodb.dev/t/p/{size}`. See [images](https://amodb.dev/images-api/). | | `popularity` | number | Relative score used by the popular list. | | `vote_average`, `vote_count` | number, integer | Aggregate user score. | | `adult`, `video` | boolean | Both are `false`. Adult titles are never served. | ### Example response `GET /3/movie/550?language=en-US&append_to_response=ratings`, with long arrays and text shortened: ```json { "adult": false, "backdrop_path": "/b9HyPoxwxjxkWEUL5ErZdhApQe2.jpg", "belongs_to_collection": null, "budget": 63000000, "genres": [ { "id": 18, "name": "Drama" }, { "id": 53, "name": "Thriller" } ], "homepage": "https://www.20thcenturystudios.com/movies/fight-club", "id": 550, "imdb_id": "tt0137523", "origin_country": [ "US", "DE" ], "original_language": "en", "original_title": "Fight Club", "overview": "A ticking-time-bomb insomniac and a slippery soap salesman channel primal male aggression into a shocking n...", "popularity": 39.0054, "poster_path": "/jSziioSwPVrOy9Yow3XhWIBDjq1.jpg", "production_companies": [ { "id": 25, "logo_path": "/nM2MfoMqzJQRiSynsDabOtFKetD.png", "name": "20th Century Fox", "origin_country": "US" }, { "id": 508, "logo_path": "/4sGWXoboEkWPphI6es6rTmqkCBh.png", "name": "Regency Enterprises", "origin_country": "US" } ], "production_countries": [ { "iso_3166_1": "US", "name": "United States of America" }, { "iso_3166_1": "DE", "name": "Germany" } ], "release_date": "1999-10-15", "revenue": 101209702, "runtime": 139, "spoken_languages": [ { "english_name": "English", "iso_639_1": "en", "name": "English" } ], "status": "Released", "tagline": "Mischief. Mayhem. Soap.", "title": "Fight Club", "video": false, "vote_average": 8.437, "vote_count": 33039, "ratings": { "imdb": { "value": 8.8, "votes": 2669989 }, "kinopoisk": { "value": 8.7, "votes": null }, "metacritic": { "value": 67, "votes": null }, "rotten_tomatoes": { "value": 81, "votes": null }, "tmdb": { "value": 8.437, "votes": 33039 } } } ``` The `ratings` block comes from `append_to_response`. Each provider is a `{value, votes}` object or `null`, as described on [ratings](https://amodb.dev/ratings/). ## Combine data with append_to_response One call can replace six. List the sub-resources you need and each arrives under its own key. The standard TMDB values work: `credits`, `videos`, `images`, `keywords`, `translations`, `external_ids`, `release_dates`, `alternative_titles`, `recommendations`, `similar`, `reviews`, `lists` and `watch/providers`. amodb adds five more. | Value | Adds | Details | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | | `ratings` | IMDb, Kinopoisk, Metacritic, Rotten Tomatoes and TMDB scores | [Ratings](https://amodb.dev/ratings/) | | `moods` | Mood meters | [Moods](https://amodb.dev/moods/) | | `soundtracks` | Tracks heard in the movie | [Soundtracks](https://amodb.dev/soundtracks/) | | `wikidata` | Wikidata id, budget, box office, awards, filming locations | [Find by external id](https://amodb.dev/find-by-external-id/) | | `showtimes` | Cinema showtimes where known | [Showtimes](https://amodb.dev/showtimes/) | Each appended block counts as part of one HTTP request. A request with ten appended values still uses one of your 20, 40 or 120 requests per minute. The appended `ratings`, `moods` and `soundtracks` blocks leave out the `id` key that the standalone paths return. ## Related movie endpoints All paths below share the base `https://api.amodb.dev/3` and the `language` parameter. | Method and path | Returns | Extra parameters | | ------------------------------------------ | -------------------------------------------- | ---------------- | | `GET /movie/{movie_id}/alternative_titles` | `{id, titles}`, often an empty array | none | | `GET /movie/{movie_id}/release_dates` | Release dates and certifications per country | none | | `GET /movie/{movie_id}/recommendations` | A list of 20 recommended movies | none | | `GET /movie/{movie_id}/similar` | A list of 20 similar movies | none | | `GET /movie/{movie_id}/reviews` | `results` is empty for most titles | none | | `GET /movie/{movie_id}/lists` | Public lists that contain the movie | `page` | | `GET /movie/{movie_id}/watch/providers` | Streaming and rental providers per country | none | | `GET /movie/latest` | The newest movie record added | none | The recommendations and similar lists always return page 1 with 20 items. The `lists` reply is paged with `page`, 20 lists per page. Paged lists elsewhere on the API take `page` from 1 to 500. Credits, images, videos, translations, keywords and external ids have their own pages: [credits](https://amodb.dev/credits/), [images](https://amodb.dev/images-api/), [videos and trailers](https://amodb.dev/videos-trailers/), [translations](https://amodb.dev/translations/), [keywords](https://amodb.dev/keywords/) and [find by external id](https://amodb.dev/find-by-external-id/). amodb does not offer the TMDB `changes` paths. ## Errors Errors use the TMDB body, for example `{"success": false, "status_code": 34, "status_message": "The resource you requested could not be found."}`. | HTTP | status_code | When | | ---- | ----------- | --------------------------------------------------------------------------- | | 401 | 7 | The key is missing or wrong. | | 402 | 36 | The plan period has ended. | | 404 | 34 | No movie with that id, a path that is not offered, or an adult title. | | 405 | 37 | You called a write method such as rating a movie. | | 429 | 25 | You went over your requests per minute. Wait for the `Retry-After` seconds. | The full list is on the [errors](https://amodb.dev/errors/) page, and limits per plan are on [rate limits](https://amodb.dev/rate-limits/). ## Practical notes - Store the `id` and `imdb_id` together. Either one finds the movie again through [find by external id](https://amodb.dev/find-by-external-id/). - Request the language you display. A text field can be empty when no translation exists in that language, so check for an empty string and re-request in `en-US` if you need a fallback. - Cache details on your side for a few hours. The server cache already holds them for 6 hours, so a shorter client cache gains nothing. - To list movies instead of reading one, see [search](https://amodb.dev/search/), [discover](https://amodb.dev/discover/) and [trending and lists](https://amodb.dev/trending-lists/). ## Questions and answers ### Do I need to change my TMDB client code? No, for the paths amodb serves. Paths, query parameters and JSON fields are the same as TMDB v3. Change the base URL to https://api.amodb.dev/3 and use your amodb key in api_key or in a Bearer header. ### How many sub-requests can append_to_response combine? Up to 20 values in one comma separated list, as in TMDB. The whole call is one HTTP request, so it counts once against your requests per minute limit. Unknown names are ignored without an error. ### Which language is used when I omit the language parameter? English (en-US). The language parameter accepts TMDB tags such as ru-RU or pt-BR. Only the 14 base languages are served, and any other tag falls back to English. ### Are TMDB write methods such as rating a movie supported? No. Account, session, rating and list write methods return 405 with status_code 37 in the TMDB error body. Read paths for titles, people, lists and search are served. A few TMDB paths such as changes are not offered. ### How fresh is the data? Movie details are cached for 6 hours, and the newest-movie endpoint for 10 minutes. A change to a record can take up to 6 hours to show in a details call. ## Related pages - [TV series API](https://amodb.dev/tv-series/): TV series API with the same paths and JSON as TMDB v3. Get a show by id with seasons, networks and the next episode, plus content ratings and watch providers. - [Credits API](https://amodb.dev/credits/): Credits API with the same paths and JSON as TMDB v3. Get cast and crew for movies, series, seasons and episodes, with order, department and job fields. - [Images API and image host](https://amodb.dev/images-api/): Movie images API with TMDB v3 paths: list posters, backdrops, logos and stills per title, then load them from img.amodb.dev in 10 sizes with no key. - [Movie and TV ratings](https://amodb.dev/ratings/): Movie ratings API that returns IMDb, Kinopoisk, Metacritic, Rotten Tomatoes and TMDB scores for a title in one call, with null for any source not known. - [Trending and list endpoints](https://amodb.dev/trending-lists/): Trending movies API with TMDB v3 paths: day and week charts, plus now playing, popular, top rated and upcoming lists for movies and TV, cached for 30 minutes. - [Quickstart](https://amodb.dev/quickstart/): Make your first amodb call: get a key, request movie details in curl, JavaScript, Python, PHP or Go, then load the poster from img.amodb.dev. Under 2 minutes. Updated: 2026-10-18. Source: https://amodb.dev/movies/