# buzz.bookhive.getReadingStats

> Published by [bookhive.buzz](https://lexicon.garden/identity/did:plc:enu2j5xjlqsjaylv3du4myh4)

✓ This is the authoritative definition for this NSID.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.getReadingStats)
- [Documentation](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.getReadingStats/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:enu2j5xjlqsjaylv3du4myh4/buzz.bookhive.getReadingStats/examples)

## Definitions

### `buzz.bookhive.getReadingStats`

**Type**: `query`

Get reading statistics for a user for a given year.

#### Parameters

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `year` | `integer` | No | The year to fetch stats for. Defaults to current year. |
| `handle` | `string` | Yes | The user handle or DID |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `year` | `integer` | Yes |  |
| `stats` | `ref` → `buzz.bookhive.getReadingStats#readingStats` | Yes |  |
| `availableYears` | `array` | Yes |  |

### `buzz.bookhive.getReadingStats#genreStat`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `count` | `integer` | Yes |  |
| `genre` | `string` | Yes |  |

### `buzz.bookhive.getReadingStats#bookSummary`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cover` | `string` | No |  |
| `title` | `string` | Yes |  |
| `hiveId` | `string` | Yes |  |
| `rating` | `integer` | No |  |
| `authors` | `string` | Yes |  |
| `pageCount` | `integer` | No |  |
| `thumbnail` | `string` | No |  |

### `buzz.bookhive.getReadingStats#readingStats`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `pagesRead` | `integer` | No |  |
| `topGenres` | `array` | Yes |  |
| `booksCount` | `integer` | Yes |  |
| `longestBook` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `shortestBook` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `averageRating` | `integer` | No | Average rating * 10 (e.g. 42 = 4.2 stars) |
| `lastBookOfYear` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `firstBookOfYear` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `mostPopularBook` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `averagePageCount` | `integer` | No |  |
| `leastPopularBook` | `ref` → `buzz.bookhive.getReadingStats#bookSummary` | No |  |
| `ratingDistribution` | `ref` → `buzz.bookhive.getReadingStats#ratingDistribution` | Yes |  |

### `buzz.bookhive.getReadingStats#ratingDistribution`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `one` | `integer` | Yes |  |
| `two` | `integer` | Yes |  |
| `five` | `integer` | Yes |  |
| `four` | `integer` | Yes |  |
| `three` | `integer` | Yes |  |

## Raw Schema

```json
{
  "id": "buzz.bookhive.getReadingStats",
  "defs": {
    "main": {
      "type": "query",
      "output": {
        "schema": {
          "type": "object",
          "required": [
            "stats",
            "availableYears",
            "year"
          ],
          "properties": {
            "year": {
              "type": "integer"
            },
            "stats": {
              "ref": "buzz.bookhive.getReadingStats#readingStats",
              "type": "ref"
            },
            "availableYears": {
              "type": "array",
              "items": {
                "type": "integer"
              }
            }
          }
        },
        "encoding": "application/json"
      },
      "parameters": {
        "type": "params",
        "required": [
          "handle"
        ],
        "properties": {
          "year": {
            "type": "integer",
            "maximum": 2100,
            "minimum": 2000,
            "description": "The year to fetch stats for. Defaults to current year."
          },
          "handle": {
            "type": "string",
            "description": "The user handle or DID"
          }
        }
      },
      "description": "Get reading statistics for a user for a given year."
    },
    "genreStat": {
      "type": "object",
      "required": [
        "genre",
        "count"
      ],
      "properties": {
        "count": {
          "type": "integer",
          "minimum": 0
        },
        "genre": {
          "type": "string"
        }
      }
    },
    "bookSummary": {
      "type": "object",
      "required": [
        "hiveId",
        "title",
        "authors"
      ],
      "properties": {
        "cover": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "hiveId": {
          "type": "string"
        },
        "rating": {
          "type": "integer"
        },
        "authors": {
          "type": "string"
        },
        "pageCount": {
          "type": "integer"
        },
        "thumbnail": {
          "type": "string"
        }
      }
    },
    "readingStats": {
      "type": "object",
      "required": [
        "booksCount",
        "ratingDistribution",
        "topGenres"
      ],
      "properties": {
        "pagesRead": {
          "type": "integer",
          "minimum": 0
        },
        "topGenres": {
          "type": "array",
          "items": {
            "ref": "buzz.bookhive.getReadingStats#genreStat",
            "type": "ref"
          }
        },
        "booksCount": {
          "type": "integer",
          "minimum": 0
        },
        "longestBook": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "shortestBook": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "averageRating": {
          "type": "integer",
          "description": "Average rating * 10 (e.g. 42 = 4.2 stars)"
        },
        "lastBookOfYear": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "firstBookOfYear": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "mostPopularBook": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "averagePageCount": {
          "type": "integer"
        },
        "leastPopularBook": {
          "ref": "buzz.bookhive.getReadingStats#bookSummary",
          "type": "ref"
        },
        "ratingDistribution": {
          "ref": "buzz.bookhive.getReadingStats#ratingDistribution",
          "type": "ref"
        }
      }
    },
    "ratingDistribution": {
      "type": "object",
      "required": [
        "one",
        "two",
        "three",
        "four",
        "five"
      ],
      "properties": {
        "one": {
          "type": "integer",
          "minimum": 0
        },
        "two": {
          "type": "integer",
          "minimum": 0
        },
        "five": {
          "type": "integer",
          "minimum": 0
        },
        "four": {
          "type": "integer",
          "minimum": 0
        },
        "three": {
          "type": "integer",
          "minimum": 0
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1
}
```