# OMDb compatible endpoint > GET https://api.amodb.dev/omdb/ answers OMDb style requests with the same parameter and field names. Look up a title by IMDb id with i or by title with t, or search with s. Poster links point to img.amodb.dev. Only r=json, movies and series are served. Change the base URL and the key, and a typical client keeps working. ## Endpoint `GET /omdb/` ```bash curl "https://api.amodb.dev/omdb/?i=tt0137523&plot=short&apikey=$AMODB_KEY" ``` Response: ```json { "Title": "Fight Club", "Year": "1999", "Rated": "R", "Released": "15 Oct 1999", "Runtime": "139 min", "Genre": "Crime, Drama, Thriller", "Director": "David Fincher", "Writer": "Chuck Palahniuk, Jim Uhls", "Actors": "Brad Pitt, Edward Norton, Meat Loaf", "Plot": "A nameless first-person narrator attends support groups in an attempt to subdue his emotional state and relieve his insomniac state.", "Language": "English", "Country": "United States, Germany", "Awards": "Nominated for 1 Oscar. 12 wins & 38 nominations total", "Poster": "https://img.amodb.dev/t/p/w300/pfPob0mrC1KiPVP9NXZnqvpks9u.jpg", "Ratings": [ { "Source": "Internet Movie Database", "Value": "8.8/10" }, { "Source": "Rotten Tomatoes", "Value": "81%" }, { "Source": "Metacritic", "Value": "67/100" } ], "Metascore": "67", "imdbRating": "8.8", "imdbVotes": "2,669,989", "imdbID": "tt0137523", "Type": "movie", "DVD": "N/A", "BoxOffice": "$38,003,039", "Production": "N/A", "Website": "N/A", "Response": "True" } ``` ## Look up a title by IMDb id or title `GET https://api.amodb.dev/omdb/` returns one title as flat JSON with OMDb field names. Pass `i` for an IMDb id such as `tt0137523`, or `t` for a title. Auth is the `apikey` query parameter. The reply has `Response` set to `True` on success and `False` on failure. The sample loads Fight Club by IMDb id and stops with the OMDb error text when `Response` is `False`. ```bash curl -sf "https://api.amodb.dev/omdb/?i=tt0137523&plot=short&apikey=$AMODB_KEY" ``` ```js const params = new URLSearchParams({ i: 'tt0137523', plot: 'short', apikey: process.env.AMODB_KEY }); const res = await fetch(`https://api.amodb.dev/omdb/?${params}`); if (!res.ok) throw new Error(`amodb returned ${res.status}`); const data = await res.json(); if (data.Response === 'False') throw new Error(data.Error); console.log(data.Title, data.Year, data.imdbRating); ``` ```python import os import requests r = requests.get( "https://api.amodb.dev/omdb/", params={"i": "tt0137523", "plot": "short", "apikey": os.environ["AMODB_KEY"]}, timeout=10, ) r.raise_for_status() data = r.json() if data["Response"] == "False": raise SystemExit(data["Error"]) print(data["Title"], data["Year"], data["imdbRating"]) ``` ```php 'tt0137523', 'plot' => 'short', 'apikey' => getenv('AMODB_KEY')]); $ch = curl_init('https://api.amodb.dev/omdb/?' . $query); curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("amodb returned $status"); } $data = json_decode($body, true); if ($data['Response'] === 'False') { throw new RuntimeException($data['Error']); } echo $data['Title'], ' ', $data['Year'], ' ', $data['imdbRating'], PHP_EOL; ``` ```go package main import ( "encoding/json" "fmt" "net/http" "net/url" "os" "time" ) type Title struct { Title string `json:"Title"` Year string `json:"Year"` ImdbRating string `json:"imdbRating"` Response string `json:"Response"` Error string `json:"Error"` } func main() { q := url.Values{"i": {"tt0137523"}, "plot": {"short"}, "apikey": {os.Getenv("AMODB_KEY")}} client := &http.Client{Timeout: 10 * time.Second} res, err := client.Get("https://api.amodb.dev/omdb/?" + q.Encode()) if err != nil { panic(err) } defer res.Body.Close() if res.StatusCode != http.StatusOK { panic(res.Status) } var t Title if err := json.NewDecoder(res.Body).Decode(&t); err != nil { panic(err) } if t.Response == "False" { panic(t.Error) } fmt.Println(t.Title, t.Year, t.ImdbRating) } ``` ### Parameters | Parameter | In | Required | Description | | --------- | ----- | -------------------- | ----------------------------------------------------------------------- | | `apikey` | query | yes | Your amodb key. | | `i` | query | one of `i`, `t`, `s` | IMDb id of the title: `tt` plus 7 to 9 digits, for example `tt0137523`. | | `t` | query | one of `i`, `t`, `s` | Title to look up, returns the best match. | | `s` | query | one of `i`, `t`, `s` | Search text of at least 3 letters, returns a list. | | `type` | query | no | `movie` or `series`. `episode` finds nothing. | | `y` | query | no | Release year. | | `plot` | query | no | `short` or `full`. Default `short`. | | `page` | query | no | Page of search results, 1 to 100. Used with `s`. | | `r` | query | no | `json` only. Any other value returns HTTP 400. | The `Season`, `Episode`, `callback` and `v` parameters from the original OMDb API are not supported and are ignored. ### Response fields | Field | Notes | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `Title`, `Year`, `Rated`, `Released`, `Runtime` | Text. `Released` reads like `15 Oct 1999`. | | `Genre`, `Director`, `Writer`, `Actors` | Comma separated names. | | `Plot`, `Language`, `Country`, `Awards` | Text. | | `Poster` | Address on `https://img.amodb.dev/t/p/w300/`. | | `Ratings` | Array of objects with `Source` and `Value`. | | `Metascore`, `imdbRating`, `imdbVotes`, `imdbID` | Text, including the vote count with commas. | | `Type` | `movie` or `series`. | | `DVD`, `BoxOffice`, `Production`, `Website` | Movies only. `BoxOffice` carries a value when known. `DVD`, `Production` and `Website` always read `N/A`. | | `totalSeasons` | Series only, as text. Series replies have no `DVD`, `BoxOffice`, `Production` or `Website`. | | `Response` | `True` or `False`, always a string. | Fields follow OMDb, so an existing OMDb parser needs no change beyond the base URL. ### Example response ```json { "Title": "Fight Club", "Year": "1999", "Rated": "R", "Released": "15 Oct 1999", "Runtime": "139 min", "Genre": "Crime, Drama, Thriller", "Director": "David Fincher", "Writer": "Chuck Palahniuk, Jim Uhls", "Actors": "Brad Pitt, Edward Norton, Meat Loaf", "Plot": "A nameless first-person narrator attends support groups in an attempt to subdue his emotional state and relieve his insomniac state.", "Language": "English", "Country": "United States, Germany", "Awards": "Nominated for 1 Oscar. 12 wins & 38 nominations total", "Poster": "https://img.amodb.dev/t/p/w300/qkrH7rjYKU4KOwwIl6wF6H3ISvm.jpg", "Ratings": [ { "Source": "Internet Movie Database", "Value": "8.8/10" }, { "Source": "Rotten Tomatoes", "Value": "81%" }, { "Source": "Metacritic", "Value": "67/100" } ], "Metascore": "67", "imdbRating": "8.8", "imdbVotes": "2,669,989", "imdbID": "tt0137523", "Type": "movie", "DVD": "N/A", "BoxOffice": "$38,003,039", "Production": "N/A", "Website": "N/A", "Response": "True" } ``` For a series such as The Wire (`i=tt0306414`), the reply ends with `"Type": "series"`, `"totalSeasons": "5"` and `"Response": "True"`. ## Search with s Send `s` to get a list instead of one title. Each page holds 10 items, and `totalResults` gives the full count as a string. Request `page=2` for items 11 to 20, and keep going until you have read `totalResults` items. A page past the last one answers `Movie not found!`. ```bash curl -sf "https://api.amodb.dev/omdb/?s=Matrix&type=movie&page=1&apikey=$AMODB_KEY" ``` | Field | Notes | | -------------- | ------------------------------------------------------------------------- | | `Search` | Array of up to 10 items with `Title`, `Year`, `imdbID`, `Type`, `Poster`. | | `totalResults` | Count of all matches, as a string. | | `Response` | `True` or `False`. | ```json { "Search": [ { "Title": "The Matrix", "Year": "1999", "imdbID": "tt0133093", "Type": "movie", "Poster": "https://img.amodb.dev/t/p/w300/kEDbym5htJgDQNenjUtSJxAHysB.jpg" }, { "Title": "The Matrix Reloaded", "Year": "2003", "imdbID": "tt0234215", "Type": "movie", "Poster": "https://img.amodb.dev/t/p/w300/d0xVNNxIYxId2qHkqpgE39soOvD.jpg" } ], "totalResults": "20", "Response": "True" } ``` The list is cut to 2 of 10 items. ## Read the Ratings array `Ratings` holds one object per source, each with `Source` and `Value`, and the `Value` is text such as `8.8/10`. The sources are `Internet Movie Database`, `Rotten Tomatoes` and `Metacritic`, and only the ones known for the title are listed. The flat fields `imdbRating`, `imdbVotes` and `Metascore` repeat some of the same data. Split `Value` on the slash if you need a number. For typed numbers and a Kinopoisk and TMDB score, use the [ratings](https://amodb.dev/ratings/) endpoint instead. ## Errors Lookup failures return `{"Response":"False","Error":"..."}`. Most of them come with HTTP 200, so read `Error` and branch on the text, not on the HTTP status alone. | `Error` text | HTTP | When | | -------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------------------------- | | `Movie not found!` | 200 | No title matches `t`, the `i` value is valid but unknown, or a search page is past the last one. | | `Incorrect IMDb ID.` | 200 | The `i` value is not shaped like an IMDb id. | | `Too many results.` | 200 | The search text is shorter than 3 letters or matches too many titles. Make the text longer or add `type` or `y`. | | `Something went wrong.` | 200 | None of `i`, `t` and `s` was sent. | | `Only r=json is supported.` | 400 | `r` is set to anything but `json`. | | `No API key provided.` or `Invalid API key!` | 401 | The `apikey` is missing or wrong. | | `Request limit reached!` | 429 | Over your requests per minute. Wait for the `Retry-After` seconds. | An ended plan answers HTTP 402. See [errors](https://amodb.dev/errors/) and [rate limits](https://amodb.dev/rate-limits/). ## Migrate an OMDb client The migration is two edits: the base URL and the key. Nothing else in the request changes. ```js // Before: the base URL and key of your current OMDb setup. // After: const OMDB_BASE = 'https://api.amodb.dev/omdb/'; const OMDB_KEY = process.env.AMODB_KEY; ``` Remove `r=xml` if you send it. A client that reads episodes, `Season` or `callback` needs another source for those parts. The rate limit is per key, so OMDb style calls and [TMDB style calls](https://amodb.dev/movies/) share one budget of 20, 40 or 120 requests per minute. ## Practical notes - Treat every value as text. Convert `Year`, `imdbRating` and `totalResults` yourself, and treat `N/A` as missing. - Use `plot=full` only when you show the long plot. `short` keeps responses smaller. - Lookups by `i` or `t` are cached longer than searches with `s`, so a repeated lookup returns the stored answer. - To get a TMDB id from an IMDb id, call [find by external id](https://amodb.dev/find-by-external-id/). - Posters are at `w300`. For other sizes, build the address from the TMDB style `poster_path` and the [images](https://amodb.dev/images-api/) size list. - Keep the key on a server. An `apikey` in a page URL is visible to every visitor. ## Questions and answers ### Do I need a different key for the OMDb endpoint? No. The same 32 character key works on the TMDB style paths and on the OMDb endpoint. Send it as the apikey query parameter, exactly as an OMDb client does today. ### Can I request XML? No. Only r=json is served. A request with r=xml returns HTTP 400 with the text Only r=json is supported., so remove that parameter or set it to json before you switch the base URL. ### Why are all values strings? The body follows OMDb field for field, and that format sends numbers such as Year, imdbRating and totalResults as strings. Convert them in your own code. Unknown values read N/A. ### Are seasons and episodes supported? No. The Season, Episode, callback and v parameters are ignored, and type=episode finds nothing. A series reply has totalSeasons but no episode data. Use the TMDB style tv endpoints for seasons. ### Where do posters come from? The Poster field holds an address on img.amodb.dev at the w300 size. Images need no key, so you can place the address straight into an img tag. ## Related pages - [OMDb API alternative](https://amodb.dev/omdb-api-alternative/): Hit the OMDb daily cap or need more than one record per call? amodb answers OMDb style requests and also serves TMDB v3 endpoints, with the same key. - [Find by external id](https://amodb.dev/find-by-external-id/): Look up a movie, series or person by IMDb, TVDB, Wikidata or Kinopoisk id with the TMDB find endpoint, and read external ids and Wikidata facts for a title. - [Movie details API](https://amodb.dev/movies/): Movie details API with the same paths and JSON as TMDB v3. Get one movie by id, add credits, ratings and moods with append_to_response, in 14 languages. - [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. - [Authentication](https://amodb.dev/authentication/): How to send your amodb key: api_key in the query, an Authorization Bearer header, or apikey for OMDb calls. Key format, storage, rotation and the 401 errors. - [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/omdb-endpoint/