> ## Documentation Index
> Fetch the complete documentation index at: https://galejames.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://galejames.mintlify.site/reference/reference-api-endpoints#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](https://galejames.mintlify.site/conceptual-guides/conceptual-guides-hitcount-analytics.md) 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.

> [!NOTE]
>
> The following Python examples use `123e4567-e89b-41d4-a716-426614174000` as the `book_id` or `test_book_id`.

```python theme={null}
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:

```json theme={null}
{
  "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:

```text theme={null}
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}`.

> [!WARNING]
>
> 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](https://galejames.mintlify.site/how-to-guides/how-to-guides-monitor-rate-limits.md) for guidance.

```python theme={null}
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:

```text theme={null}
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:

```python theme={null}
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:

```text theme={null}
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:

```python theme={null}
# 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.

```python theme={null}
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](https://galejames.mintlify.site/conceptual-guides/conceptual-guides-hitcount-analytics) — Learn how `hitCount` tracks customer interest in specific titles.

### How to guides

* [Migrate to BookHub Publisher API v2](https://galejames.mintlify.site/how-to-guides/how-to-guides-migrate-bookhub.md) — Update your code to use BookHub Publisher API v2’s new features.
* [Migrate away from title sorting](https://galejames.mintlify.site/how-to-guides/how-to-guides-migrate-away-from-title-sorting.md) — Update your code to remove title sorting in BookHub Publisher API v2.

### Reference

* [Track high–performing books with `hitCount`](https://galejames.mintlify.site/reference/reference-code-examples#track-high-performing-books-with-hitcount) — Example code for using the `hitCount` field in PHP.
* [Endpoint coverage for the `hitCount` field](https://galejames.mintlify.site/reference/reference-data-models) — Learn which BookHub Publisher API endpoints include the `hitCount` field in their responses.
* [Release notes](https://galejames.mintlify.site/reference/reference-release-notes.md) — Explore all changes in BookHub Publisher API v2.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.