/api/v1/search Search works, people and series together
One ranked page mixing all three kinds, ordered by full-text relevance. Every result carries a kind discriminator.
Matching is by whole word or word prefix (the last word of the query is treated as a prefix), over work titles and subtitles and the names of authors, narrators and series. Punctuation is a word boundary on both sides, so "Halo: Primordium", "Halo.Primordium" and "Halo Primordium" are the same query - except that a run of single-letter fragments (an initialism) stays one adjacent phrase, so "Q&A" and "M*A*S*H" keep their selectivity rather than matching every row holding those letters apart. A possessive matches in either spelling: a word of four or more characters ending in a single s also matches the possessive it may be with its apostrophe dropped, so "enders game" finds "Ender's Game", and a possessive written with its apostrophe also matches the word stored without one, so "finnegan's wake" finds "Finnegans Wake".
Two boosts run ahead of the relevance hits. A query that IS a work's title - compared whole, ignoring case, spacing and punctuation, including a possessive's apostrophe - returns that work FIRST; several works sharing the title all lead, in id order. A query that names a series and a number - "jack reacher 2", "jack reacher book 2", "jack reacher #2" - resolves that volume and returns it next. An exact title leads a resolved volume, since the title is an equality and the volume an inference. A query that IS a series' name ranks that series first among the page's series rows, the primary series ahead of same-named translations and reading-order variants (see searchSeries); those rows take the place of the page's first series row, and every other row keeps its relative order. Series on the page sharing one name are ordered the same way within the places they already hold, so a half-typed "harry pot" lists the primary first among them too. A window smaller than the relevance tie may hold same-named translations or variants and not their primary; when those rows name it (translation_of, ordering_of) under the same name, it is pulled onto the page and ranked ahead of them, even beside an unrelated series of that name, so a linked same-named primary can appear although the relevance window did not hold it - never one outside lang, whose filter also decides what counts as the primary (under lang=de a German edition is the primary of its name). A reading-order variant of a translation brings the translation and the original it translates. The page stays exactly limit long, so a boost costs the last hit rather than widening the response, and a query that resolves none of them returns the plain relevance page.
lang narrows the page to works in the named languages, inside the query - so ?lang=de&limit=20 returns up to 20 German hits - and the boosts obey it too: a work outside the filter never leads. People always pass (a person has no language), and so does a series whose members tie between languages.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
| q * | query | string | The search query. Matching is by whole word or word prefix, with punctuation as a word boundary - though an initialism (a run of single-letter fragments, as in "Q&A") is matched as one adjacent phrase, and a possessive matches in either spelling ("enders" finds "Ender's", "finnegan's" finds "Finnegans"); an empty or whitespace-only value is a 400, while a value holding no word at all (only punctuation) is an ordinary empty result page. |
| limit | query | integer | default 20, 1-50 How many results to return. Capped at 50; a non-numeric or non-positive value falls back to the default (20) rather than being clamped to 1. |
| lang | query | string | Only works in these languages: one code or several separated by commas (de, de,en); a repeated parameter reads as one list. Matched by primary subtag, so de also matches a work tagged de-at, and a regional item (pt-br) matches as its primary subtag. Absent or empty means every language. At most 8 codes; an item that is not a language tag is a 400, while a code the catalogue holds no works in simply matches nothing. A record with no language - a person, or a series whose members tie - is never excluded. Against an artifact older than the languages layer the value is validated and then ignored. |
| source | query | string | Only works with at least one recording from this source type, for example librivox for the free public-domain LibriVox recordings. The filter runs inside the query, the boosts obey it, and on the combined search it scopes the page to works (a person or a series has no recording). A value that is not a source type of the schema is a 400. Against an artifact older than version 8 a filtered list is empty. |
* required
Responses
{
"results": [
<WorkResult | PersonResult | SeriesResult>
]
} q was missing, empty or whitespace only, a lang item is not a language tag, or source names no source type. {
"error": string
} Retry-After seconds and retry. The answer carries Cache-Control: no-store. {
"error": string
} {
"error": string
} Retry-After reports the wait the server's refresh loop is on. {
"error": string
}