Rank books by hitCount to find top performers

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

The hitCount field in the BookWithAnalytics schema provides a count of how many times a book’s details have been retrieved via the GET /v2/books/{bookId} endpoint. You can use this to track the popularity and performance of books over time. This guide shows you how to retrieve hitCount, rank your catalog by it, and flag high performers — then, optionally, measure a marketing campaign’s impact.

Only requests made by buyers increment hitCount, providing an accurate reflection of buyer interest in each book. Requests from publishers or cached responses do not affect the count, ensuring that the metric specifically tracks genuine buyer engagement. For details on hitCount data type, initial value, update behavior, and availability, see hitCount field explained.

Prerequisites

Before you begin, ensure you meet the following prerequisites:

• Familiarity with the BookHub Publisher API v2.
• A valid JWT for authentication.
• Access to your codebase that integrates with the BookHub Publisher API.

Tips

The following examples show how to use the hitCount field correctly and what to avoid. See hitCount Analytics for more information.

✅ Good uses

• Identifying trending books over weeks/months
• Measuring marketing campaign effectiveness
• Generating internal reports

❌ Avoid

• Making instant inventory decisions based on a single view count.
• Using it as the sole metric for success.
• Treating it as perfectly accurate (may have slight delays in updates).

Step 1: Retrieve book details with hitCount

To see the hitCount for a specific book, make a GET request to the GET /v2/books/{bookId} endpoint.

The following Python examples use 123e4567-e89b-41d4-a716-426614174000 as the book_id or test_book_id.

import requests

BASE_URL = "https://api.bookhub.com/api"
TOKEN = "YOUR_JWT_TOKEN"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(
    f"{BASE_URL}/v2/books/123e4567-e89b-41d4-a716-426614174000",
    headers=HEADERS
)
response.raise_for_status()
book = response.json()['data']
hit_count = book.get('hitCount', 0)
print(f"{book['title']} ({book['bookId']}): {book['hitCount']} views")

The response will include the hitCount field, which indicates how many times that book’s details have been accessed via the API. For 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
  }
}

The print statement outputs:

The Great Adventure (123e4567-e89b-41d4-a716-426614174000): 1247 views

Step 2: Retrieve hitCount for all books and identify top performers

The GET /v2/books endpoint does not include hitCount in its response. To retrieve hitCount for all books, fetch each book individually using GET /v2/books/{bookId}.

This approach makes one API request per book, so the number of requests scales linearly with your catalog size. For large catalogs, this may exceed the rate limit (150 requests per minute). See Monitor rate limits for guidance.

import time

def get_book_with_retry(book_id, max_retries=3):
    """Fetch a single book, waiting out rate limits if needed."""
    url = f"{BASE_URL}/v2/books/{book_id}"
    for attempt in range(max_retries):
        response = requests.get(url, headers=HEADERS)
        if response.status_code == 429:
            reset = int(response.headers.get('X-RateLimit-Reset', 0))
            wait_seconds = min(60, max(1, reset - int(time.time())))
            print(f"Rate limit hit — waiting {wait_seconds}s before retrying {book_id}")
            time.sleep(wait_seconds)
            continue
        response.raise_for_status()
        return response.json()['data']
    raise Exception(f"Failed to fetch {book_id} after {max_retries} retries")

# Fetch all books to get bookId values
list_response = requests.get(f"{BASE_URL}/v2/books", headers=HEADERS)
list_response.raise_for_status()
books = list_response.json()['data']['books']

# Fetch hitCount for each book individually, respecting rate limits
book_performance = []
for book in books:
    detail = get_book_with_retry(book['bookId'])
    book_performance.append({
        'title': detail['title'],
        'bookId': detail['bookId'],
        'hitCount': detail.get('hitCount', 0)
    })

# Sort by hitCount descending
book_performance.sort(key=lambda x: x['hitCount'], reverse=True)

for book in book_performance:
    print(f"{book['title']} ({book['bookId']}): {book['hitCount']} views")

The output lists books sorted by performance:

The Great Adventure (123e4567-e89b-41d4-a716-426614174000): 1247 views
Mystery at Midnight (123e4567-e89b-41d4-a716-426614174001): 980 views
Cooking with Love (123e4567-e89b-41d4-a716-426614174002): 450 views

Step 3: Set a performance threshold

To identify high–performing books, you can set a threshold for the hitCount. For example, you might want to flag any book with a hitCount greater than 1000 as a high performer. You can implement this logic in your code as follows:

for book in book_performance:
    status = "⭐ High performer" if book['hitCount'] > 1000 else ""
    print(f"{book['title']} ({book['bookId']}): {book['hitCount']} views {status}")

Response

After running Step 3, the output identifies high performers:

The Great Adventure (123e4567-e89b-41d4-a716-426614174000): 1247 views ⭐ High performer
Mystery at Midnight (123e4567-e89b-41d4-a716-426614174001): 980 views 
Cooking with Love (123e4567-e89b-41d4-a716-426614174002): 450 views 

Step 4: Test your implementation

Retrieve a known book and confirm hitCount is returned and processed correctly:

# Example test case
test_book_id = "123e4567-e89b-41d4-a716-426614174000"  # Replace with a valid bookId
response = requests.get(
    f"{BASE_URL}/v2/books/{test_book_id}",
    headers=HEADERS
)
response.raise_for_status()
book = response.json()['data']
print(f"{book['title']} ({book['bookId']}): {book['hitCount']} views")

Optional: Measure marketing campaign effectiveness

Once you can retrieve hitCount, you can reuse it to measure a campaign’s impact by comparing counts before and after. This is a separate use case from ranking — use it when you’re evaluating a specific promotion.

before = requests.get(f"{BASE_URL}/v2/books/123e4567-e89b-41d4-a716-426614174000", headers=HEADERS).json()['data']['hitCount']
# ... run campaign ...
after = requests.get(f"{BASE_URL}/v2/books/123e4567-e89b-41d4-a716-426614174000", headers=HEADERS).json()['data']['hitCount']
increase = after - before
print(f"Campaign generated {increase} additional views")

Next steps

Explore related topics:

Conceptual guides

• Using the hitCount field for analytics — Learn how hitCount tracks customer interest in specific titles.

How to guides

• Migrate to BookHub Publisher API v2 — Update your code to use BookHub Publisher API v2’s new features.
• Migrate away from title sorting — Update your code to remove title sorting in BookHub Publisher API v2.

Reference

• Track high–performing books with hitCount — Example code for using the hitCount field in PHP.
• Endpoint coverage for the hitCount field — Learn which BookHub Publisher API endpoints include the hitCount field in their responses.
• Release notes — Explore all changes in BookHub Publisher API v2.

---