# Book Reader Stats API
> Live reader-community stats for books from Open Library (the Internet Archive's open book catalog) — no key, nothing stored. This is the reading-community view of a book: how readers rate it and how many want to read, are reading or have already read it, distinct from the plain book-catalog and reading-trends APIs in the catalogue — this is the community-engagement layer, not the bibliographic record. The book endpoint returns a title's reader stats: the average rating, the full 1-5 star distribution, and the reading-log counts (want-to-read, currently-reading, already-read), with its authors, first-published year and subjects. The search endpoint searches books and returns each match with its rating and want-to-read count, so you can find a work and its Open Library id. The author endpoint returns an author's profile — work count, top work and dates. Build reading dashboards, book-recommendation widgets, "most wanted" charts and community-sentiment tools on top of real Open Library data. Look up a book by its Open Library work id (work=OL27448W) or by title (title=the hobbit); reading-log counts come from the community's bookshelves.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/bookstats-api/..."
```

## Pricing
- **Free** (Free) — 25,000 calls/Mo, 3 req/s
- **Starter** ($5/Mo) — 330,000 calls/Mo, 10 req/s
- **Pro** ($14/Mo) — 1,400,000 calls/Mo, 25 req/s
- **Scale** ($33/Mo) — 5,000,000 calls/Mo, 55 req/s

## Endpoints

### Book

#### `GET /v1/book` — A book reader stats — ratings and reading-log

**Parameters:**
- `work` (query, optional, string) — Open Library work id Example: `OL27448W`
- `title` (query, optional, string) — Book title Example: `the hobbit`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/book?work=OL27448W&title=the+hobbit"
```

**Response:**
```json
{
    "data": {
        "title": "The Lord of the Rings",
        "author": "J.R.R. Tolkien",
        "source": "Open Library",
        "work_id": "OL27448W",
        "subjects": [
            "The Lord of the Rings",
            "Fiction",
            "Ficción",
            "English Fantasy fiction",
            "Ficción fantástica inglesa",
            "Fantasy fiction",
            "Open Library Staff Picks",
            "Middle Earth (Imaginary place)"
        ],
        "already_read": 222,
        "rating_count": 112,
        "want_to_read": 2272,
        "rating_average": 4.438,
        "first_published": "September 3, 2001",
        "open_library_url": "https://openlibrary.org/works/OL27448W",
        "currently_reading": 191,
        "star_distribution": {
            "1": 3,
            "2": 5,
            "3": 9,
            "4": 18,
            "5": 77
        }
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:14.738Z",
        "request_id": "2c818ef7-43b9-4a7a-83fb-4a83b1a473ab"
    },
    "status": "ok",
    "message": "Book retrieved successfully",
    "success": true
}
```

### Search

#### `GET /v1/search` — Search books with ratings and want-to-read

**Parameters:**
- `q` (query, required, string) — Search query Example: `dune`
- `limit` (query, optional, string) — Results (1-25) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/search?q=dune&limit=10"
```

**Response:**
```json
{
    "data": {
        "count": 10,
        "query": "dune",
        "total": 44544,
        "source": "Open Library",
        "results": [
            {
                "title": "Dune",
                "author": "Frank Herbert",
                "work_id": "OL893415W",
                "already_read": 681,
                "rating_count": 423,
                "want_to_read": 3284,
                "rating_average": 4.305,
                "first_published": 1965
            },
            {
                "title": "Dune Messiah",
                "author": "Frank Herbert",
                "work_id": "OL893526W",
                "already_read": 244,
                "rating_count": 137,
                "want_to_read": 530,
                "rating_average": 3.956,
                "first_published": 1969
            },
            {
                "title": "Children of Dune",
                "author": "Frank Herbert",
                "work_id": "OL893516W",
                "already_read": 126,
                "rating_count": 42,
                "want_to_read": 267,
                "rating_average": 4,
                "first_published": 1976
            },
            {
                "title": "Heretics of Dune",
                "author": "Frank Herbert",
                "work_id": "OL893502W",
                "already_read": 91,
                "rating_count": 50,
                "want_to_read": 131,
                "rating_average": 3.86,
                "first_published": 1984
 
…(truncated, see openapi.json for full schema)
```

### Author

#### `GET /v1/author` — An author profile — work count, top work

**Parameters:**
- `author` (query, required, string) — Author name Example: `brandon sanderson`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/author?author=brandon+sanderson"
```

**Response:**
```json
{
    "data": {
        "name": "Brandon Sanderson",
        "source": "Open Library",
        "top_work": "The Final Empire",
        "author_key": "OL1394865A",
        "birth_date": "19 December 1975",
        "death_date": null,
        "work_count": 190,
        "top_subjects": [
            "Fiction, fantasy, general",
            "Fiction",
            "Fiction, fantasy, epic",
            "Fantasy",
            "Fantasy fiction",
            "New York Times bestseller",
            "Children's fiction",
            "Magic"
        ],
        "open_library_url": "https://openlibrary.org/authors/OL1394865A"
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:15.677Z",
        "request_id": "7d3ffd39-1893-42a8-9a44-2336c228d2bf"
    },
    "status": "ok",
    "message": "Author retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Look up a book by its Open Library work id (work=OL27448W) or by title (title=the hobbit). Reading-log counts (want-to-read, currently-reading, already-read) come from the community's bookshelves.",
        "source": "Open Library public API (openlibrary.org, live)",
        "service": "bookstats-api",
        "endpoints": {
            "GET /v1/book": "A book's reader stats — rating distribution and reading-log counts (work=OL27448W or title=dune).",
            "GET /v1/meta": "This document.",
            "GET /v1/author": "An author's profile — work count, top work, dates (author=brandon sanderson).",
            "GET /v1/search": "Search books with ratings and want-to-read counts (q=dune)."
        },
        "description": "Live reader-community stats for books from Open Library (the Internet Archive's open book catalog). The reading-community view of a book — how readers rate it and how many want to read, are reading or have already read it. book = a title's reader stats (average rating, full 1-5 star distribution, reading-log counts, authors, year, subjects); search = search books, each with its rating and want-to-read count; author = an author's profile (work count, top work, dates). Live, no key, nothing stored. The community-engagement layer, distinct from the plain book-catalog and reading-trends APIs.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:15.771Z",
        "request_id":
…(truncated, see openapi.json for full schema)
```

### Books

#### `GET /v1/isbn` — Resolve an ISBN to its book, edition details and work id

**Parameters:**
- `isbn` (query, required, string) — ISBN-10 or ISBN-13 Example: `9780547928227`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/isbn?isbn=9780547928227"
```

**Response:**
```json
{
    "data": {
        "isbn": "9780547928227",
        "pages": 300,
        "title": "The Hobbit",
        "source": "Open Library",
        "work_id": "OL27482W",
        "subtitle": null,
        "work_url": "https://openlibrary.org/works/OL27482W",
        "languages": [
            "eng"
        ],
        "publishers": [
            "Mariner Books"
        ],
        "publish_date": "2012",
        "physical_format": "Paperback",
        "open_library_url": "https://openlibrary.org/isbn/9780547928227"
    },
    "meta": {
        "timestamp": "2026-06-13T13:54:29.068Z",
        "request_id": "3f242447-aaac-4366-95fb-8ff3619b7f29"
    },
    "status": "ok",
    "message": "ISBN resolved successfully",
    "success": true
}
```

### Authors

#### `GET /v1/author-works` — An author bibliography, each book with rating and want-to-read

**Parameters:**
- `author` (query, required, string) — Author name Example: `brandon sanderson`
- `sort` (query, optional, string) — rating, new, old, already_read or want_to_read Example: `rating`
- `limit` (query, optional, string) — Results (1-50) Example: `15`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/bookstats-api/v1/author-works?author=brandon+sanderson&sort=rating&limit=15"
```

**Response:**
```json
{
    "data": {
        "sort": "rating",
        "count": 15,
        "works": [
            {
                "title": "Words of Radiance",
                "work_id": "OL16813053W",
                "already_read": 149,
                "rating_count": 89,
                "want_to_read": 268,
                "edition_count": 22,
                "rating_average": 4.685,
                "first_published": 2012,
                "open_library_url": "https://openlibrary.org/works/OL16813053W"
            },
            {
                "title": "The Hero of Ages",
                "work_id": "OL5738154W",
                "already_read": 176,
                "rating_count": 120,
                "want_to_read": 178,
                "edition_count": 27,
                "rating_average": 4.583,
                "first_published": 2008,
                "open_library_url": "https://openlibrary.org/works/OL5738154W"
            },
            {
                "title": "The Way of Kings",
                "work_id": "OL15358691W",
                "already_read": 242,
                "rating_count": 155,
                "want_to_read": 826,
                "edition_count": 30,
                "rating_average": 4.535,
                "first_published": 2010,
                "open_library_url": "https://openlibrary.org/works/OL15358691W"
            },
            {
                "title": "Oathbringer",
                "work_id": "OL17834026W",
                "already_read": 125,
         
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/bookstats-api
OpenAPI spec: https://www.oanor.com/api/bookstats-api/openapi.json