BookSearch API

Programmatic search over the BeyondBSR book catalogue plus BSR history retrieval for a single book. Two endpoints, JSON in / JSON out, API-key auth.

When to use this skill

Use it when the user asks to:

• Find books matching numeric filters: BSR range, rating, reviews count, royalty, page count age, publication recency.
• Discover niches by keyword inclusion/exclusion or Amazon category IDs.
• Filter by marketplace (Amazon.com, .co.uk, .de, .fr, .it, .es, .ca).
• Distinguish self-publishers from traditional publishers.
• Estimate sales (daily / weekly / monthly / quarterly) and revenue per copy.
• Compare BSR averages across multiple time windows (7d / 30d / 90d / 180d / 365d).
• Retrieve the BSR timeline of a single book (by domainId + asin) over the last N days, e.g. for charting rank evolution.

Do NOT use for: price-history charts, review/rating timelines, account/user data, or anything not in the response schemas below. Those are out of scope.

Endpoints

POST https://beyondbsr.com/api/v1/books/search
GET  https://beyondbsr.com/api/v1/books/{domainId}/{asin}/bsr-history?days={1..365}
Content-Type: application/json   (search only)
X-API-Key: $BOOKSEARCH_API_KEY

Authentication

• Read the key from the BOOKSEARCH_API_KEY env var. Format: bbsr_live_<43-char-base64url>.
• Never print, echo, log, or include the key in any user-facing output. Never paste it into another tool's input.
• On 401 Unauthorized: do not retry. Report "API key missing or invalid — check BOOKSEARCH_API_KEY env var" and stop.
• Send X-API-Key exactly once. Multi-valued headers are rejected.

Marketplace domains

Map natural-language marketplace references (e.g. "Amazon.de", "the UK store", "amazon italia") to domainId using this table:

IDs 5 and 7 are intentional gaps in the dataset — do not invent them. The validator technically accepts 1–12, but only the seven IDs above are guaranteed to return data. If the user asks for a marketplace not listed (e.g. Japan, Australia), tell them it is not currently supported.

Request schema

All fields are optional except domainId. Enums accept either the string name (e.g. "Weekly") or the integer value.

Required

BSR filters

Product filters

Quality filters

Economic filters

Discovery

Pagination

Workflow

1. Marketplace — Identify domainId from intent using the marketplace table. If ambiguous (e.g. "Amazon"), ask which country.
2. Translate — Map every natural-language filter to its schema field. Don't guess enum values; use the table.
3. Pagination — Default to limit: 50. Raise to 100–300 only if the user explicitly wants many results. Start with offset: 0.
4. Send — POST the JSON body. Inspect the status code first.
5. Paginate if needed — If returnedCount == limit, more results likely exist. Offer to fetch the next page with offset += limit.
6. Present — Surface title, asin, bsr, sales/revenue estimates, and a clickable cover URL (see response notes).

Example request

{
  "domainId": 3,
  "bsrType": "Days90",
  "bsrMin": 1,
  "bsrMax": 50000,
  "bindingType": "Paperback",
  "publisherType": "SelfPublishersOnly",
  "ratingMin": 4.0,
  "reviewsMin": 10,
  "interiorType": "BlackWhite",
  "vatType": "Reduced",
  "royaltyMin": 2.50,
  "royaltyMax": 15.00,
  "monthsSincePublicationMax": 24,
  "includePreOrders": false,
  "includeKeywords": ["journal", "notebook"],
  "excludeKeywords": ["coloring"],
  "categoryIds": [266162, 3248921],
  "limit": 50,
  "offset": 0
}

Example cURL

curl -X POST "https://beyondbsr.com/api/v1/books/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BOOKSEARCH_API_KEY" \
  -d '{
    "domainId": 3,
    "bsrType": "Days90",
    "bsrMax": 50000,
    "bindingType": "Paperback",
    "publisherType": "SelfPublishersOnly",
    "ratingMin": 4.0,
    "limit": 50
  }'

Response schema

Envelope — BookSearchApiResponse

Result item — BookSearchResultDto (most relevant fields)

Important caveats

• All royalty and revenue fields are in cents — divide by 100 before showing currency.
• bsr ≠ bsrCurrent. bsr is whatever column was chosen by bsrType; bsrCurrent is always the latest snapshot.
• In bsrType=Historical mode, the avgBsrXd averages come from the current snapshot table while bsr itself is the historical month value — there is a documented temporal asymmetry inside the same response. Mention this if the user is doing a strict historical analysis.

BSR History endpoint

Single-ASIN BSR timeline. Returns raw snapshots from the time-series store, ordered ascending by recordedAt.

GET https://beyondbsr.com/api/v1/books/{domainId}/{asin}/bsr-history?days={1..365}
X-API-Key: $BOOKSEARCH_API_KEY
Accept: application/json

When to use

• The user has a specific ASIN and wants its BSR over time (chart, drill-down, sanity-check the search-time avgBsrXd averages).
• The user wants to verify a book's recent rank trajectory (e.g. "is it gaining or losing visibility?").

If the user has filter criteria but no specific ASIN, use POST /search first, then call this endpoint per ASIN of interest.

Path & query parameters

Example request

GET /api/v1/books/1/1635864348/bsr-history?days=90
X-API-Key: $BOOKSEARCH_API_KEY
Accept: application/json

Example cURL

curl -X GET "https://beyondbsr.com/api/v1/books/1/1635864348/bsr-history?days=90" \
  -H "X-API-Key: $BOOKSEARCH_API_KEY" \
  -H "Accept: application/json"

Response schema — BookBsrHistoryApiResponse

BsrPointDto:

Example body:

{
  "asin": "1635864348",
  "domainId": 1,
  "fromUtc": "2026-01-27T00:00:00Z",
  "toUtc": "2026-04-27T00:00:00Z",
  "pointCount": 412,
  "points": [
    { "recordedAt": "2026-01-27T03:14:00Z", "bestSellersRank": 1234 },
    { "recordedAt": "2026-01-27T15:02:00Z", "bestSellersRank": 1218 }
  ]
}

Status codes (BSR history specific)

Caveats

• Granularity is raw: Keepa snapshots arrive 1–4× per day on actively-tracked books. A 365-day window typically yields 365–1460 points. No daily aggregation is applied.
• The endpoint returns only (recordedAt, bestSellersRank). Use POST /search if you also need rating/review/price data.
• ASIN is case-sensitive — must be uppercase. 1635864348 (all digits) is valid.
• Default 365 days is the cap. Longer histories are not exposed; do not retry with days > 365.

Status codes & error handling

Example 400 body

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "DomainId": ["DomainId must be between 1 and 12."],
    "Limit": ["Limit must be between 1 and 300."]
  }
}

Sorting & pagination notes

• Default sort: ORDER BY <chosen BSR column> ASC (lower BSR = better seller appears first).
• Historical mode (bsrType=Historical + bsrYear/bsrMonth): sorted by the historical monthly BSR rank ASC.
• Tie-breaker is non-deterministic — books with identical BSR may appear in different orders across page fetches. Warn the user if they need a perfectly stable ordering.
• No orderBy parameter is exposed.

Limits

• Rate limit: 120 requests/minute per API key. Shared across all callers using the same key.
• Body size: 128 KB max.
• Page size: 300 results max per request (limit ≤ 300).
• Offset cap: 100,000 (deep pagination beyond this is not supported — refine filters instead).