Using the hitCount field for analytics

Learn how hitCount tracks customer interest in specific titles.

The hitCount increments each time a buyer retrieves the book via GET /v2/books/{bookId}. Requests authenticated with publisher credentials do not increment the count. Use it to track the popularity and performance of books over time.

The hitCount field is available only in v2. It is not supported in v1.

Use hitCount to measure interest in specific titles, such as tracking post-campaign API calls to assess marketing impact and make data-driven decisions about inventory and pricing.

How it works

The hitCount field is read-only and initially set to 0 when a book is created. Each time customers retrieve the book’s details via the GET /v2/books/{bookId} endpoint, the hitCount increments by 1. This count is cumulative and persists throughout the book’s lifetime, allowing you to track its performance over time.

The hitCount field is updated in real time and reflects the total number of times an API call accessed the book’s details. Updates typically appear within seconds; this isn’t a guaranteed SLA. Client-side caching using If-None-Match and ETag headers returns a 304 Not Modified response without incrementing hitCount, since the server returns 304 without invoking the API call’s tracking logic.

Each API call from the same customer increases the hitCount, since it tracks total API requests rather than unique users. However, API calls made by publishers do not affect the hitCount, as these requests are authenticated with your publisher credentials and do not represent buyer-facing traffic.

For error responses and rate limit details, see Error codes.

When you retrieve a book’s details using the GET /v2/books/{bookId} endpoint, the response includes the hitCount field, allowing you to see how many times a customer’s API call retrieved the book’s details. The following example shows a full response, including the hitCount:

Get a specific book request example

curl --request GET \
  --url https://api.bookhub.com/api/v2/books/123e4567-e89b-41d4-a716-426614174000 \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Get a specific book response example

{
  "status": "success",
  "data": {
    "bookId": "123e4567-e89b-41d4-a716-426614174000",
    "title": "The Great Adventure",
    "author": "Jane Smith",
    "description": "An epic tale of courage and discovery",
    "language": "en-US",
    "publisher": "Adventure Books Inc",
    "publishedDate": "2024-03-15",
    "isbn": "978-0-1234-5678-9",
    "price": 24.99,
    "status": "ACTIVE",
    "coverImages": [
      "https://covers.bookhub.com/great-adventure-front.jpg"
    ],
    "genres": [
      "Fiction",
      "Adventure"
    ],
    "bookFormat": "Hardcover",
    "createdDate": "2024-12-25T10:30:00Z",
    "updatedDate": "2024-12-26T15:45:00Z",
    "hitCount": 1247
  }
}

See Get a specific book for more information about the GET /v2/books/{bookId} endpoint.

Next steps

Explore related topics:

How-to guides

• Rank books by hitCount to find top performers — Use the hitCount field to rank books by buyer interest and flag your top performers.

Reference

• Endpoint coverage for the hitCount field — Learn which BookHub Publisher API endpoints include the hitCount field in their responses.
• Get a specific book — Learn about the GET /v2/books/{bookId} endpoint, including the hitCount field.
• Track high-performing books with hitCount — Example code for using the hitCount field in PHP.
• Error codes — Understand the error codes returned by the BookHub Publisher API.

---