Movie details

curl --request GET \
  --url https://api.simkl.com/movies/{id} \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'

{
  "title": "Inception",
  "year": 2010,
  "type": "movie",
  "ids": {
    "simkl": 472214,
    "slug": "inception",
    "tmdb": "27205",
    "imdb": "tt1375666",
    "tvdbmslug": "inception",
    "tvdbm": "113",
    "fb": "inception",
    "offen": "http://inceptionmovie.warnerbros.com/",
    "letterslug": "inception",
    "traktmslug": "inception-2010",
    "jwslug": "inception"
  },
  "rank": 20,
  "droprate": "0.1%",
  "poster": "14/14017865947c9d3d0d",
  "fanart": "27/2745964f37d66f1bb",
  "released": "2010-07-15",
  "runtime": 148,
  "director": "Christopher Nolan",
  "certification": "PG-13",
  "budget": 160000000,
  "revenue": 839030630,
  "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
  "genres": [
    "Action",
    "Adventure",
    "Science Fiction",
    "Thriller"
  ],
  "country": "US",
  "language": "EN",
  "alt_titles": [
    {
      "name": "Origine",
      "lang": 17,
      "type": "official"
    },
    {
      "name": "Inception",
      "lang": 22,
      "type": "official"
    },
    {
      "name": "Origine",
      "lang": 7,
      "type": "synonym"
    }
  ],
  "ratings": {
    "simkl": {
      "rating": 8.6,
      "votes": 11454
    },
    "imdb": {
      "rating": 8.8,
      "votes": 2816410
    }
  },
  "trailers": [
    {
      "name": "Official Trailer",
      "youtube": "Jvurpf91omw",
      "size": 1080
    },
    {
      "name": "Official New UK Trailer",
      "youtube": "JE9z-gy4De4",
      "size": 1080
    }
  ],
  "release_dates": [
    {
      "iso_3166_1": "US",
      "results": [
        {
          "type": 1,
          "release_date": "2010-07-13"
        },
        {
          "type": 3,
          "release_date": "2010-07-16"
        },
        {
          "type": 5,
          "release_date": "2010-12-07"
        }
      ]
    },
    {
      "iso_3166_1": "GB",
      "results": [
        {
          "type": 1,
          "release_date": "2010-07-08"
        },
        {
          "type": 3,
          "release_date": "2010-07-16"
        }
      ]
    }
  ],
  "users_recommendations": [
    {
      "title": "Interstellar",
      "year": 2014,
      "poster": "20/2052598c2716ef054",
      "type": "movie",
      "ids": {
        "simkl": 250822,
        "slug": "interstellar"
      }
    },
    {
      "title": "The Dark Knight",
      "year": 2008,
      "poster": "16/16943077cdd27f0cc6",
      "type": "movie",
      "ids": {
        "simkl": 53282,
        "slug": "the-dark-knight"
      }
    },
    {
      "title": "Fight Club",
      "year": 1999,
      "poster": "53/53342766816af5a20",
      "type": "movie",
      "ids": {
        "simkl": 53894,
        "slug": "fight-club"
      }
    }
  ]
}

Movie details

Full detail record for one movie — title, overview, year, runtime, country, language, certification, genres, director, ratings, posters, fanart, external IDs, alternate titles, release-date list per region, budget, revenue, trailers, similar-movie recommendations. The default response is already complete; no flags needed.

Responses are Cloudflare-cached by Simkl ID, so repeat lookups of popular titles are near-free. Parallel requests against this endpoint are explicitly allowed (see Rate limits → Parallel requests).

Cache invalidation is automatic. When Simkl updates the underlying record (admin edits, automated metadata refresh, image swap, related-titles change, etc.), the corresponding Cloudflare cache entry is purged server-side. The next call to this endpoint returns the fresh data — there’s no TTL to wait out and no client-side cache-busting needed. Your own app-level cache, if any, still has to be invalidated by your client.

Use a Simkl ID for the lookup. If you only have an external ID, resolve it via GET /redirect first.

Which IDs can I send/expect? All accepted input identifiers and the keys you’ll see echoed back in responses are listed at Standard media objects → Supported ID keys. Send every ID you have on writes — Simkl picks the first that resolves and ignores the rest. Reminder: slug is response-only (never send it on a request).

GET

movies

{id}

Movie details

curl --request GET \
  --url https://api.simkl.com/movies/{id} \
  --header 'User-Agent: <user-agent>' \
  --header 'simkl-api-key: <api-key>'

{
  "title": "Inception",
  "year": 2010,
  "type": "movie",
  "ids": {
    "simkl": 472214,
    "slug": "inception",
    "tmdb": "27205",
    "imdb": "tt1375666",
    "tvdbmslug": "inception",
    "tvdbm": "113",
    "fb": "inception",
    "offen": "http://inceptionmovie.warnerbros.com/",
    "letterslug": "inception",
    "traktmslug": "inception-2010",
    "jwslug": "inception"
  },
  "rank": 20,
  "droprate": "0.1%",
  "poster": "14/14017865947c9d3d0d",
  "fanart": "27/2745964f37d66f1bb",
  "released": "2010-07-15",
  "runtime": 148,
  "director": "Christopher Nolan",
  "certification": "PG-13",
  "budget": 160000000,
  "revenue": 839030630,
  "overview": "Cobb, a skilled thief who commits corporate espionage by infiltrating the subconscious of his targets is offered a chance to regain his old life as payment for a task considered to be impossible: \"inception\", the implantation of another person's idea into a target's subconscious.",
  "genres": [
    "Action",
    "Adventure",
    "Science Fiction",
    "Thriller"
  ],
  "country": "US",
  "language": "EN",
  "alt_titles": [
    {
      "name": "Origine",
      "lang": 17,
      "type": "official"
    },
    {
      "name": "Inception",
      "lang": 22,
      "type": "official"
    },
    {
      "name": "Origine",
      "lang": 7,
      "type": "synonym"
    }
  ],
  "ratings": {
    "simkl": {
      "rating": 8.6,
      "votes": 11454
    },
    "imdb": {
      "rating": 8.8,
      "votes": 2816410
    }
  },
  "trailers": [
    {
      "name": "Official Trailer",
      "youtube": "Jvurpf91omw",
      "size": 1080
    },
    {
      "name": "Official New UK Trailer",
      "youtube": "JE9z-gy4De4",
      "size": 1080
    }
  ],
  "release_dates": [
    {
      "iso_3166_1": "US",
      "results": [
        {
          "type": 1,
          "release_date": "2010-07-13"
        },
        {
          "type": 3,
          "release_date": "2010-07-16"
        },
        {
          "type": 5,
          "release_date": "2010-12-07"
        }
      ]
    },
    {
      "iso_3166_1": "GB",
      "results": [
        {
          "type": 1,
          "release_date": "2010-07-08"
        },
        {
          "type": 3,
          "release_date": "2010-07-16"
        }
      ]
    }
  ],
  "users_recommendations": [
    {
      "title": "Interstellar",
      "year": 2014,
      "poster": "20/2052598c2716ef054",
      "type": "movie",
      "ids": {
        "simkl": 250822,
        "slug": "interstellar"
      }
    },
    {
      "title": "The Dark Knight",
      "year": 2008,
      "poster": "16/16943077cdd27f0cc6",
      "type": "movie",
      "ids": {
        "simkl": 53282,
        "slug": "the-dark-knight"
      }
    },
    {
      "title": "Fight Club",
      "year": 1999,
      "poster": "53/53342766816af5a20",
      "type": "movie",
      "ids": {
        "simkl": 53894,
        "slug": "fight-club"
      }
    }
  ]
}

Authorizations

simkl-api-key

string

header

default:YOUR_CLIENT_ID

required

Optional alias for the client_id query parameter. Simkl accepts your client_id either as the simkl-api-key request header or as the ?client_id=… query parameter — pick one. The query-parameter form is preferred because it makes the request fully self-describing in URL form.

Headers

User-Agent

string

required

Descriptive identifier for your app, ideally name/version. Examples: PlexMediaServer/1.43.1.10540, kodi-simkl/0.9.2, MyApp/2.4.1 (https://myapp.com).

Path Parameters

string

required

Simkl ID for the item. Simkl IDs are stable, unambiguous, and the response is Cloudflare-cached by Simkl ID, so repeat lookups are very fast.

If you only have an external ID (IMDb, TMDB, TVDB, MAL, AniDB, etc.), resolve it to a Simkl ID first via GET /redirect — it returns the Simkl ID in the Location header without a JSON payload, and the follow-up detail call is Cloudflare-cached.

Query Parameters

client_id

string

required

Your client_id from your Simkl developer settings. Required on every request.

app-name

string

required

Short, lowercase identifier for your app (e.g. plex-scrobbler, kodi-bridge). Helps Simkl identify which apps are using the API.

app-version

string

required

Your app's current version (e.g. 1.0, 2.4.1). Helps Simkl debug issues you report.

Response

Full movie record returned by GET /movies/{id}. The response shape is the same regardless of any extended query value — the parameter is a legacy no-op for this endpoint. Responses are Cloudflare-cached by Simkl ID. See Null and missing values for the nullable-field semantics used below.

title

string

required

Display title in the response language (defaults to English unless the request's language overrides it).

year

integer

required

Release year.

type

enum<string>

required

Always movie on this endpoint.

Available options:

movie

ids

object

required

External and internal identifiers for an item. Pass as many as you have — Simkl resolves to the canonical record.

Hide child attributes

ids.simkl

integer

Simkl internal ID. Most reliable.

Example:

53536

ids.slug

string

URL-safe slug returned in responses.

Example:

"attack-on-titan"

ids.imdb

string

IMDb ID.

Example:

"tt0181852"

ids.tmdb

string

TMDb ID.

Example:

"296"

ids.tvdb

TVDB ID or slug.

Example:

153021

ids.mal

string

MyAnimeList ID.

Example:

"4246"

ids.anidb

string

AniDB ID. Specifying just this is enough for anime lookups.

Example:

"10846"

ids.anilist

string

AniList ID.

Example:

"21"

ids.kitsu

string

Kitsu ID.

Example:

"12"

ids.anisearch

string

aniSearch ID.

Example:

"2227"

ids.animeplanet

string

Anime-Planet slug.

Example:

"one-piece"

ids.livechart

string

LiveChart ID.

Example:

"321"

ids.letterboxd

string

Letterboxd slug.

Example:

"the-truman-show"

ids.netflix

string

Netflix movie ID.

Example:

"70210890"

ids.hulu

string

Hulu episode ID.

ids.crunchyroll

string

Crunchyroll episode ID.

ids.traktslug

string

Trakt slug.

Example:

"john-wick-chapter-4-2023"

Example:

{
  "simkl": 53536,
  "imdb": "tt0181852",
  "tmdb": 296
}

rank

integer | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Position in Simkl's popularity ranking. Null when not ranked.

droprate

string | null

Percentage of users who started watching but dropped, e.g. "0.1%". Type 4 null when the metric isn't computed.

poster

string | null

Poster image path. Compose the full URL via Images. Type 4 null when no poster on file.

fanart

string | null

Background/hero image path. Type 4 null when no fanart on file.

released

string<date> | null

Initial release date (YYYY-MM-DD). Type 4 null when unknown.

runtime

integer | null

Runtime in minutes. Type 4 null when not on file.

director

string | null

Primary director. Type 4 null when unknown.

certification

string | null

Content rating (e.g. PG-13, R). Type 4 null when not rated for the response country.

budget

integer | null

Production budget in USD. Type 4 null when not on file.

revenue

integer | null

Box-office revenue in USD. Type 4 null when not on file.

overview

string | null

Plot synopsis. Type 4 null when no overview is available.

genres

string[]

Genre names.

country

string

ISO 3166-1 alpha-2 production country code.

language

string

ISO 639-1 language code in UPPERCASE.

alt_titles

object[]

Localized and alternate titles. May contain many entries for popular titles.

Hide child attributes

alt_titles.name

string

alt_titles.lang

integer

Simkl internal language code.

alt_titles.type

enum<string>

Classification of an entry in alt_titles. official = broadcaster/distributor-supplied localization, short = shortened form, synonym = community-supplied alias, original = original-language title (typically Japanese for anime).

Available options:

official,

short,

synonym,

original

ratings

object

Ratings keyed by source. Movies always carry simkl and imdb.

Hide child attributes

ratings.simkl

object

External-source rating.

Hide child attributes

ratings.simkl.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.simkl.votes

integer

Number of votes contributing to the rating.

ratings.imdb

object

External-source rating.

Hide child attributes

ratings.imdb.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.imdb.votes

integer

Number of votes contributing to the rating.

ratings.{key}

object

External-source rating.

Hide child attributes

ratings.{key}.rating

number

Rating value (0–10).

Required range: 0 <= x <= 10

ratings.{key}.votes

integer

Number of votes contributing to the rating.

trailers

object[] | null

YouTube-hosted trailers and promo clips. Type 4 null when no trailers on file.

Hide child attributes

trailers.youtube

string

required

YouTube video ID (not a full URL).

trailers.name

string | null

Type 4 null — data not on file in that field's slot. See Null and missing values.

trailers.size

integer | null

Type 4 null — data not on file in that field's slot. See Null and missing values. Max video resolution height (720, 1080, 2160).

release_dates

object[]

Per-country release event timeline.

Hide child attributes

release_dates.iso_3166_1

string

required

ISO 3166-1 alpha-2 country code.

release_dates.results

object[]

required

Hide child attributes

release_dates.results.type

integer

required

Release-event type: 1 = premiere, 2 = theatrical limited, 3 = theatrical wide, 4 = digital, 5 = physical, 6 = TV.

release_dates.results.release_date

string<date>

required

users_recommendations

object[]

Mini media objects suggested by Simkl based on this title's viewers.

Hide child attributes

users_recommendations.title

string

users_recommendations.year

integer | null

Type 4 null — data not on file in that field's slot. See Null and missing values.

users_recommendations.poster

string | null

Type 4 null — data not on file in that field's slot. See Null and missing values.

users_recommendations.type

string

users_recommendations.ids

object

Hide child attributes

users_recommendations.ids.simkl

integer

users_recommendations.ids.slug

string

About Movies

Movies by genre

⌘I