FullDatasets
Datasets
Use cases Docs
Sign up
Docs

API reference

Search books

GET /v1/books/search

Full-text browse with filters.

Markdown Full spec OpenAPI

Full-text search over editions. Use this to browse. To identify a known title, use match instead.

MCP: search_books { "q": "Project Hail Mary", "limit": 5 }

When to use

  • Filtered exploration (year, language, subject)
  • “Show me books like…”

Do not search an ISBN. Do not use search as the first call when the user named one book — match ranks and collapses better for that.

Request

curl -sS -H "Authorization: Bearer $FDS_API_KEY" \
  "https://api.fulldatasets.com/v1/books/search?q=Project%20Hail%20Mary&limit=5"
Query Required Notes
q one of q or genre Title-ish query. Do not put a genre name or an author-only string here
author no Rank filter on names. Not AND’d into title FTS
year no publication_year
language no e.g. eng
subject no Exact raw OL tag (Magicians -- Fiction)
genre no Closed facet: fantasy, science_fiction, mystery, romance, …
kind no primary | graphic | derivative | audio | set | any. Default prefers primary
limit no Default 20, max 100
cursor no Pagination from next_cursor

Response `200`

{
  "results": [{ "id": "fds_ed_…", "title": "Project Hail Mary" }],
  "next_cursor": "fds_ed_…"
}

Each item is a book object. next_cursor is null when there is no next page.

Ranking

  1. Folded title_key / title_normalized variants first (articles, apostrophes, subtitles)
  2. Open Library shelf/rating popularity among those hits (genre browse uses this first)
  3. Title-only websearch_to_tsquery fallback — author tokens are not AND’d into FTS
  4. Prefer primary (novel/text). Graphic novels, companions, and study guides are demoted unless kind=graphic or the query itself looks graphic
  5. One canonical edition per work

Browse genre with genre=fantasy (no q). That matches edition subjects, not a w.genres column. q=epic fantasy still searches titles and will look like keyword spam.

Author-only: GET /v1/authors/search. “Books like these”: recommend.

Search is short-TTL and hits Postgres (not the 24h point-lookup cache).

Errors

Status code When
400 bad_request Missing both q and genre

See also