La référence de l’API n’est disponible qu’en anglais.

Discovery/lookup

Turn one external identifier - IMDb, TMDB, TVDB - or a catalog UUID into our title id, with every identifier we hold for it. Spends no verification.

Paramètres

• imdb_idstringfacultatif

  An IMDb id, e.g. tt9218128. Supply exactly one of the four identifiers.

  Plus⌄

  An IMDb id (for example tt9218128). Supply exactly ONE of imdb_id, tmdb_id, tvdb_id and uuid; none or several is a 400.

• tmdb_idstringfacultatif

  A TMDB id. Exactly one identifier; a number shared by a film and a series is a 409.

  Plus⌄

  A TMDB id. Supply exactly one identifier. TMDB numbers films, series, seasons and episodes separately, so a number that matches more than one of them is a 409 rather than a guess.

• tvdb_idstringfacultatif

  A TVDB id. Exactly one identifier.

  Plus⌄

  A TVDB id. Supply exactly one of the four identifiers.

• uuidstring · uuidfacultatif

  A catalog UUID. Exactly one identifier.

  Plus⌄

  A catalog UUID in canonical 8-4-4-4-12 form. Supply exactly one of the four identifiers.

• languagestringfacultatif

  Response language, a supported BCP-47 tag. Default en.

  Plus⌄

  A supported BCP-47 tag. Defaults to en. An UNSUPPORTED tag is a 400 naming the accepted set, never a silent fallback - the catalogue stores match the 17 tags as exact strings, so degrading would answer an empty 200 that an integrator would ship before noticing.

Champs de la réponse

• idstring
• uuidstring · uuid
• typestring
• titlestring
• yearintegerpeut être null
• matched_onpublic_id | uuid | slug | imdb_id | tmdb_id | tvdb_id

  WHICH identifier resolved the lookup. The one field of this response a caller cannot derive from the rest, and the reason a caller passing a mixed batch can tell what we matched on.

• external_idsobject · ExternalIds

  EVERY external id we hold, not just the one asked with. The point of a lookup is to cross a namespace, so echoing back only the key supplied would answer nothing.

  Afficher 3 champs

En-têtes de réponse

• X-Request-ID

  The id of this request, on every response - success or error. Quote it to support: it is how we find your request in our logs. An X-Request-ID you send is honoured and echoed back, so you can use your own; otherwise we generate one. /v1 error bodies carry no trace id of their own.

• X-Quota-Reset

  RFC 3339 instant at which the billing period rolls. Present on every response to a request whose key was metered - every 2xx, every error a handler returned, and the quota 429. Absent on a refusal that happens before metering: a missing or unknown key (401), a restricted key or a plan that does not carry the endpoint (403), a public demo-key gate refusal, and the pre-authentication flood throttle.

• X-Calls-Remaining

  Requests left in the period after this one, never below 0. Present whenever X-Quota-Reset is (see there for when a response carries no quota headers).

• X-Verifications-Remaining

  How many verifications you can still make before a limit stops you. The daily limit and the monthly allowance are counted separately; this is whichever of the two runs out first. Sent whenever X-Quota-Reset is.

• X-Quota-Grace

  true when THIS request fell inside the 10% grace band above a monthly ceiling. A grace request is served and is not billed; treat true as "back off now", not as headroom. Always true or false, never absent when the other quota headers are present.

• Retry-After429

  Seconds to wait before retrying. On every 429 - the quota hard stop, the public demo key's limits, and the pre-authentication flood throttle (which carries this header alone, because no key has been read yet).

• X-Demo-Challenge-ModeUniquement avec la clé de démonstration

  Sent only on responses to the public demo key. The value interactive asks the documentation page to show the visible verification widget - it is sent once a browser has made more than five runs in ten minutes or has received a 429. The page then repeats the header, X-Demo-Challenge-Mode: interactive, on its next request, with the widget's token in X-Demo-Challenge. Requests made with your own key never receive it.

Erreurs

• 400not exactly one of imdb_id, tmdb_id, tvdb_id and uuid was supplied

  validation-failed

• 400uuid is not a canonical UUID

  validation-failed

• 400language is not one of the 17 supported tags

  validation-failed

• 401no key, or a key that is unknown, malformed, expired or revoked

  unauthenticated

• 403the key's own scope, IP or referrer restriction excludes this request

  forbidden

• 403your key carries no plan, or the public demo key was used with a method other than GET or HEAD

  plan-required

• 403a browser call with the public demo key sent no valid bot-check token

  challenge-required

• 404the identifier is well-formed but matches no record

  not-found

• 405the HTTP method is not GET

  validation-failed

• 409a tmdb_id matches more than one TMDB namespace (film, series, season or episode)

  conflict

• 410the matched record has been removed

  gone

• 429your plan's daily or monthly request ceiling is reached; the refused call is not charged

  quota-exhausted

• 429too many requests from your address before any key is read; with the public demo key, its per-address, per-network or global limit, a temporary block, or too many demo requests in flight at once

  rate-limited

• 503we could not meter or serve the request right now; retry with backoff

  upstream-unavailable