Search an EPUB's text
GET /assets/{id}/epub/search
Finds text in the chapters of an EPUB asset and returns each match with its chapter and a short excerpt.
Matching ignores case and looks for the exact characters, so “run” also matches “running” and “brunch”; there’s no stemming or whole-word matching. Each chapter’s text is searched with tags removed and spaces collapsed, including the title in its head but not scripts or styles. Chapters are searched in reading order, up to 5 matches per chapter and 200 in all, and a chapter that can’t be read is skipped without notice, so results can be incomplete. Results aren’t cached, so each search that goes ahead opens the book again.
You need to be signed in, and any account can search any EPUB asset.
A q shorter than 2 bytes once surrounding spaces are trimmed, such
as a single ASCII letter, returns an empty list without looking up
the asset, so it says nothing about whether the asset exists. A 404
means no asset has that id, it’s in the trash or it has no stored
file. A missing or repeated q gets a plain-text 400, and server
errors get a plain-text 500, not the JSON shown.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The id of the EPUB asset.
Query Parameters
Section titled “Query Parameters ”The text to find. Surrounding spaces are trimmed and case is
ignored. Anything shorter than 2 bytes, an empty q included,
returns an empty list.
Responses
Section titled “ Responses ”The matches, in reading order. The list can be empty.
One match from an EPUB search.
object
The position of the chapter the match is in, as idx in the chapter list.
Currently always “Chapter N”, with N = chapter_idx + 1, not the label the chapter list shows.
An excerpt of the chapter’s text around char_offset: up to 60 bytes before it and up to the query’s length plus 60 bytes after it, with ”…” where the text was cut. It normally holds the match, but if lowercasing changed the length of earlier text it can be shifted. The cut is made by bytes, so a character at either end can come out broken.
Where the match starts, as a byte offset (not a character count) into the chapter’s text with tags removed, spaces collapsed and letters lowercased. Lowercasing can change the length of some non-ASCII text, so the offset may not line up with the original text.
Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Resource not found
object
Human-readable error summary
Example
the request could not be completedUnexpected server error
object
Human-readable error summary
Example
the request could not be completed