Skip to main content
GET
Movie details

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

id
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

OK

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.

Example:
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.

ratings
object

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

trailers
object[] | null

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

release_dates
object[]

Per-country release event timeline.

users_recommendations
object[]

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