API 參考文件僅提供英文版。

Discovery/discover

Browse the catalogue by genre, year range, country, type and minimum rating, in one of four fixed sort orders. Returns title ids. Spends no verification.

參數

• genrestring[]選填

  A genre slug from /v1/genres. Repeat to require several (ANDed).

  更多⌄

  Repeatable. Multiple genres are ANDed.

• year_frominteger選填

  Earliest release year, inclusive, 1874-2200.

  更多⌄

  Inclusive lower bound of a RANGE. Supplying only one end is fine - the other is filled from the bounds below. An inverted range (year_from after year_to) is a 400, and so is a year outside 1874-2200.

• year_tointeger選填

  Latest release year, inclusive, 1874-2200; not before year_from.

  更多⌄

  Inclusive upper bound of the same range. See year_from.

• countrystring[]選填

  A production country code. Repeat for several (any of them).

  更多⌄

  Only titles produced in this country, given as the country code the title record's countries field uses. Repeatable; several match ANY of them. An unknown code matches nothing rather than failing.

• typemovie | tv_movie | short | series | mini_series | special選填預設值：all types

  One title type, e.g. movie. Omit for every type.

  更多⌄

  One title type. Omit for every type. Case-insensitive; shown here in lowercase. An unlisted value is a 400 naming these.

• min_ratingstring選填

  Lowest aggregate rating, 0-10. Decimals allowed.

  更多⌄

  Only titles whose aggregate rating is at least this value, on a 0-10 scale; decimals allowed (7.5). Anything else is a 400 naming the field min_rating.

• sortnewest | rating | popularity | alphabetical選填預設值：popularity

  newest, rating, popularity (default) or alphabetical.

  更多⌄

  One of newest, rating, popularity, alphabetical. Each carries a fixed direction; there is no descending form, and a leading minus is a 400 rather than an order this API cannot actually produce. An unrecognised token is a 400 naming the accepted set. Case-insensitive; shown here in lowercase.

• languagestring選填

  Response language, a supported BCP-47 tag. Default en. Not an original-language filter.

  更多⌄

  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.

• limitinteger選填預設值：20

  Ids per page, 1-50. Default 20.

  更多⌄

  Out of range is a 400, never a silent clamp - silent clamping hides client bugs until they surface as a support ticket.

• cursorstring選填

  The previous page's next_cursor. Bound to every filter and the sort.

  更多⌄

  Opaque and FILTER-BOUND. Replaying a cursor after any filter changes is a 400 CURSOR_INVALID, never a silently wrong page.

回應欄位

• itemsstring[]
• next_cursorstring可為 null
• totalinteger · int64可為 null

  How many items the query matches in total, when that is known. Null when it is not known; it is never an estimate.

回應標頭

• 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-Mode僅限示範金鑰

  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.

錯誤

• 400year_from or year_to is outside 1874-2200 or not an integer, or year_to is earlier than year_from

  validation-failed

• 400type is not a recognised title type

  validation-failed

• 400sort is not newest, rating, popularity or alphabetical

  validation-failed

• 400min_rating is not a number from 0 to 10

  validation-failed

• 400limit is not an integer or is outside 1-50

  validation-failed

• 400language is not one of the 17 supported tags

  validation-failed

• 400cursor is malformed, stale, or was issued for different filters or sort - start again from the first page

  cursor-invalid

• 400a cursor names a position beyond the 100,000-result paging ceiling

  cursor-invalid

• 400with the public demo key, a cursor past the second page or one the demo key was not given

  cursor-invalid

• 400with the public demo key, limit above 10

  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

• 405the HTTP method is not GET

  validation-failed

• 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