vooks-catalog

Official Python client for the Vooks Public Catalog API: a library of ad-free animated read-along storybooks, audiobooks and ebooks for children roughly ages 2 to 8.

Reads need no credential. No key, no registration, no form. A token only raises the rate limit from 600 to 3,000 requests a minute and unlocks catalog exports.

No runtime dependencies. A dependency in a published SDK is a dependency in every project that installs it, and urllib is enough for nine reads and one write.

pip install vooks-catalog

from vooks_catalog import VooksCatalog

vooks = VooksCatalog()

page = vooks.list_titles(q="dinosaurs", age=4, limit=5)
for title in page["data"]:
    print(title["title"], title["url"])

Pagination

list_titles, list_topics and titles are cursor-paginated. list_plans is not: there are four plans and it returns them all.

titles() follows the cursor for you. Prefer list_titles when you only need the first page, because this makes a request per page.

for title in vooks.titles(language="spanish"):
    print(title["title"])

Errors

An HTTP error response raises VooksApiError, carrying the API's stable machine-readable code. Branch on that, not on the message.

A transport failure, where the request never got an answer, raises whatever urllib raised: there is no status or code to report, so wrapping it would invent one.

from vooks_catalog import VooksApiError

try:
    vooks.get_title("no-such-slug")
except VooksApiError as error:
    if error.code == "not_found":
        ...
    print(error.status, error.code, error.retry_after_seconds)

retry_after_seconds is set when the server sent a Retry-After, in either form RFC 9110 allows. A date rounds up, so a date 400ms away gives 1, never 0. A literal Retry-After: 0 is kept as 0. It is None when the server sent no header, when the value will not parse, or when the date has already passed, because "said nothing" and "retry now" are different answers.

Sandbox

A fixed, tiny catalog that never changes and never touches the live library.

from vooks_catalog import VooksCatalog, SANDBOX_BASE_URL

sandbox = VooksCatalog(base_url=SANDBOX_BASE_URL)

Command line

vooks search dinosaurs --age 4
vooks title 10-little-fish
vooks topics
vooks plans
vooks search bedtime --json

Reading on

• Developer guide
• OpenAPI 3.1
• Agent index
• Node and TypeScript client