# Reading Trends API
> A live read on what the Open Library reading community is into right now, as an API. Pull the trending books over the last day, week, month or year — with author, first-published year and edition count — or open a book for its social reading stats: the average star rating and number of ratings, and how many people have it on their "want to read", "currently reading" and "already read" shelves. The pulse of community reading delivered as clean JSON for book, social and dashboard apps. Live data, no key. Distinct from book-catalogue search/ISBN APIs — this is the reading-popularity and shelf-engagement layer.

## 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/readingtrends-api/..."
```

## Pricing
- **Free** (Free) — 700 calls/Mo, 5 req/s
- **Starter** ($6/Mo) — 14,500 calls/Mo, 15 req/s
- **Pro** ($14/Mo) — 66,000 calls/Mo, 30 req/s
- **Business** ($37/Mo) — 330,000 calls/Mo, 50 req/s

## Endpoints

### Trends

#### `GET /v1/search` — Reading-engagement search — books with rating and shelf counts

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

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

**Response:**
```json
{
    "data": {
        "books": [
            {
                "id": "OL893415W",
                "url": "https://openlibrary.org/works/OL893415W",
                "title": "Dune",
                "author": "Frank Herbert",
                "authors": [
                    "Frank Herbert"
                ],
                "cover_id": 11481354,
                "already_read": 686,
                "rating_count": 426,
                "want_to_read": 3291,
                "edition_count": 120,
                "rating_average": 4.31,
                "first_published": 1965,
                "currently_reading": 251
            },
            {
                "id": "OL893526W",
                "url": "https://openlibrary.org/works/OL893526W",
                "title": "Dune Messiah",
                "author": "Frank Herbert",
                "authors": [
                    "Frank Herbert"
                ],
                "cover_id": 2421405,
                "already_read": 244,
                "rating_count": 137,
                "want_to_read": 530,
                "edition_count": 70,
                "rating_average": 3.96,
                "first_published": 1969,
                "currently_reading": 41
            },
            {
                "id": "OL893516W",
                "url": "https://openlibrary.org/works/OL893516W",
                "title": "Children of Dune",
                "author": "Frank Herbert",
                "authors": [
                    "Frank He
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/subject` — The most-held books in a subject/genre

**Parameters:**
- `subject` (query, required, string) — Subject/genre slug Example: `fantasy`
- `limit` (query, optional, string) — Results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/readingtrends-api/v1/subject?subject=fantasy&limit=25"
```

**Response:**
```json
{
    "data": {
        "books": [
            {
                "id": "OL138052W",
                "url": "https://openlibrary.org/works/OL138052W",
                "rank": 1,
                "title": "Alice's Adventures in Wonderland",
                "author": "Lewis Carroll",
                "authors": [
                    "Lewis Carroll"
                ],
                "cover_id": 10527843,
                "edition_count": 3547,
                "first_published": 1865
            },
            {
                "id": "OL18417W",
                "url": "https://openlibrary.org/works/OL18417W",
                "rank": 2,
                "title": "The Wonderful Wizard of Oz",
                "author": "L. Frank Baum",
                "authors": [
                    "L. Frank Baum"
                ],
                "cover_id": 552443,
                "edition_count": 2049,
                "first_published": 1899
            },
            {
                "id": "OL24034W",
                "url": "https://openlibrary.org/works/OL24034W",
                "rank": 3,
                "title": "Treasure Island",
                "author": "Robert Louis Stevenson",
                "authors": [
                    "Robert Louis Stevenson"
                ],
                "cover_id": 13859660,
                "edition_count": 1988,
                "first_published": 1880
            },
            {
                "id": "OL20600W",
                "url": "https://openlibrar
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/trending` — Trending books by period

**Parameters:**
- `period` (query, optional, string) — now, daily, weekly, monthly, yearly or forever Example: `daily`
- `limit` (query, optional, string) — Results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/readingtrends-api/v1/trending?period=daily&limit=25"
```

**Response:**
```json
{
    "data": {
        "books": [
            {
                "id": "OL17930368W",
                "url": "https://openlibrary.org/works/OL17930368W",
                "rank": 1,
                "title": "Atomic Habits",
                "author": "James Clear",
                "authors": [
                    "James Clear"
                ],
                "cover_id": 12539702,
                "edition_count": 40,
                "first_published": 2016
            },
            {
                "id": "OL2010879W",
                "url": "https://openlibrary.org/works/OL2010879W",
                "rank": 2,
                "title": "Rich Dad, Poor Dad",
                "author": "Robert T. Kiyosaki",
                "authors": [
                    "Robert T. Kiyosaki",
                    "Sharon L. Lechter"
                ],
                "cover_id": 8315603,
                "edition_count": 115,
                "first_published": 1990
            },
            {
                "id": "OL1968368W",
                "url": "https://openlibrary.org/works/OL1968368W",
                "rank": 3,
                "title": "The 48 Laws of Power",
                "author": "Robert Greene",
                "authors": [
                    "Robert Greene"
                ],
                "cover_id": 6424160,
                "edition_count": 55,
                "first_published": 1998
            },
            {
                "id": "OL21640039W",
                "url": "h
…(truncated, see openapi.json for full schema)
```

### Books

#### `GET /v1/book` — A book's social reading stats

**Parameters:**
- `id` (query, required, string) — Open Library work id Example: `OL17930368W`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/readingtrends-api/v1/book?id=OL17930368W"
```

**Response:**
```json
{
    "data": {
        "book": {
            "id": "OL17930368W",
            "url": "https://openlibrary.org/works/OL17930368W",
            "title": "Atomic Habits",
            "subjects": [
                "Habit",
                "Habit breaking",
                "Behavior modification",
                "Self-actualization (psychology)",
                "Business",
                "psychology",
                "Personal Growth",
                "New York Times bestseller",
                "BUSINESS & ECONOMICS / Organizational Behavior",
                "PSYCHOLOGY / Social Psychology",
                "SELF-HELP / Personal Growth / General."
            ],
            "already_read": 1643,
            "rating_count": 1372,
            "want_to_read": 54599,
            "rating_average": 3.97,
            "first_published": null,
            "currently_reading": 4673
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:04.260Z",
        "request_id": "ce53f1a0-ad59-4a8c-a1c2-d75343d488d5"
    },
    "status": "ok",
    "message": "Book stats retrieved successfully",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "source": "Open Library trending + ratings + bookshelves (live)",
        "periods": [
            "now",
            "daily",
            "weekly",
            "monthly",
            "yearly",
            "forever"
        ],
        "service": "readingtrends-api",
        "endpoints": {
            "GET /v1/book": "A book's social reading stats (id=OL17930368W: ratings + shelf counts).",
            "GET /v1/meta": "This document.",
            "GET /v1/trending": "Trending books by period (period=now|daily|weekly|monthly|yearly|forever, limit)."
        },
        "description": "Live reading-community trends from Open Library: trending books by day/week/month/year (with author, year and edition count), and per-book social reading stats — average rating, rating count, and want-to-read / currently-reading / already-read shelf counts. Live, no key. Distinct from book-catalogue search/ISBN APIs — this is the reading-popularity and engagement layer.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:06.297Z",
        "request_id": "7cf3081d-d7c9-4298-8711-34ed12e54586"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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