API 参考文档仅提供英文版本。

Discovery/search

Relevance search across titles and people. Every response carries a titles list and a people list, and the two page separately. Spends no verification.

参数

• qstring必填

  The search text. Required, at least 2 characters.

  更多⌄

  Minimum two characters. A shorter query is a 400 rather than a false "no results".

• typeall | movie | tv_movie | short | series | mini_series | season | episode | special | person可选默认值：all

  all (default), person for people only, or one title type.

  更多⌄

  Narrows the titles list to one type. person returns people only. Without it, or with all, you get both lists. Any other type narrows titles and still returns matching people. Case-insensitive; shown here in lowercase. An unlisted value is a 400 naming these.

• yearinteger可选

  A release year. Narrows titles to that year; people are unaffected.

  更多⌄

  Only titles released in this year. An integer; people results are not affected.

• languagestring可选

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

  更多⌄

  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

  Results per list, 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 title list's next_cursor from the previous page. Bound to the same filters.

  更多⌄

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

• people_cursorstring可选

  The people list's next_cursor. Pages independently of cursor.

  更多⌄

  Advances the PEOPLE list. The two lists page independently - see the response schema.

响应字段

• querystring

  The query as it was searched, which can differ from what was sent (a leading article is removed, for example). When you show "results for ...", show this value.

• titlesobject · TitleHitPage

  A cursor-paginated list. next_cursor is null on the last page, and only there - it is never an empty string and never omitted. The last page carries its items together with the null cursor, so you can stop as soon as you see it, without requesting an empty page.

  显示 3 个字段
• peopleobject · PersonHitPage

  A cursor-paginated list. next_cursor is null on the last page, and only there - it is never an empty string and never omitted. The last page carries its items together with the null cursor, so you can stop as soon as you see it, without requesting an empty page.

  显示 3 个字段
• languagestring

响应标头

• 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.

错误

• 400q is missing or shorter than 2 characters

  validation-failed

• 400type is not one of the ten documented values, or year is not an integer

  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 or people_cursor names a position beyond the 100,000-result paging ceiling

  cursor-invalid

• 400with the public demo key, any cursor or people_cursor - the demo key gets the first page only

  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