# Using the CardSight AI API - Catalog Statistics API

## Overview
Get aggregate statistics about the CardSight AI catalog, including total counts of cards, releases, sets, manufacturers, and segments.

## Endpoint Details
- **Method**: GET
- **URL**: `https://api.cardsight.ai/v1/catalog/statistics`
- **Authentication**: None required (public endpoint)

## Parameters
This endpoint has no parameters.

## Using the CardSight AI SDK (Recommended)

### Node.js / TypeScript
```typescript
import { CardSightAI } from 'cardsightai'

const client = new CardSightAI({ apiKey: 'your-api-key' })

const response = await client.catalog.statistics()

// Always check for errors
if (response.error) {
  console.error('Error:', response.error)
} else {
  const stats = response.data

  console.log('=== Catalog Statistics ===')
  console.log(`Total Cards: ${stats.cards.total.toLocaleString()}`)
  console.log(`  Base Cards: ${stats.cards.base.toLocaleString()}`)
  console.log(`  Variations: ${stats.cards.variations.toLocaleString()}`)
  console.log(`  Parallels: ${stats.cards.parallels.toLocaleString()}`)
  console.log(`Total Releases: ${stats.releases.total.toLocaleString()}`)
  console.log(`Total Sets: ${stats.sets.total.toLocaleString()}`)
  console.log(`  Identifiable: ${stats.sets.identifiable.toLocaleString()}`)
  console.log(`Manufacturers: ${stats.manufacturers.total}`)
  console.log(`Segments: ${stats.segments.total}`)
  console.log(`Parallel Types: ${stats.parallels.total}`)
}
```

### Python
```python
from cardsightai import CardSightAI

client = CardSightAI(api_key='your-api-key')

response = client.catalog.statistics()

print(f"Total Cards: {response.cards.total:,}")
print(f"Total Releases: {response.releases.total:,}")
print(f"Manufacturers: {response.manufacturers.total}")
```

## Direct API Call (cURL)
```bash
curl -X GET "https://api.cardsight.ai/v1/catalog/statistics"
```

## Example Response
```json
{
  "segments": {
    "total": 12,
    "breakdown": [
      { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Baseball", "count": 2500 }
    ]
  },
  "manufacturers": {
    "total": 45,
    "breakdown": [
      { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Topps", "releaseCount": 1200 }
    ]
  },
  "releases": {
    "total": 8765,
    "bySegment": [
      {
        "segmentName": "Baseball",
        "total": 2500,
        "byYear": [
          { "year": "2023", "count": 150 },
          { "year": "2022", "count": 145 }
        ]
      }
    ]
  },
  "sets": {
    "total": 45678,
    "identifiable": 40000
  },
  "cards": {
    "total": 5234567,
    "base": 4123456,
    "variations": 111111,
    "parallels": 1000000
  },
  "parallels": {
    "total": 23456,
    "fullSet": 12345,
    "partial": 11111
  }
}
```

## Response Fields

| Field | Type | Description |
|-------|------|-------------|
| segments | object | Segment statistics with breakdown |
| manufacturers | object | Manufacturer statistics with breakdown |
| releases | object | Release statistics by segment |
| sets | object | Set statistics |
| cards | object | Card statistics |
| parallels | object | Parallel type statistics |

### Segments Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total number of segments |
| breakdown | array | Array of segment breakdown items |

Each breakdown item contains: `id` (UUID), `name` (string), `count` (number of releases)

### Manufacturers Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total number of manufacturers |
| breakdown | array | Array of manufacturer breakdown items |

Each breakdown item contains: `id` (UUID), `name` (string), `releaseCount` (number)

### Releases Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total releases across all years |
| bySegment | array | Array of segment release breakdowns |

Each bySegment item contains: `segmentName` (string), `total` (number), `byYear` (array of `{year, count}`)

### Sets Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total number of card sets |
| identifiable | number | Sets that can be recognized by AI |

### Cards Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total cards including all parallel versions |
| base | number | Base cards (non-parallel, non-variation) |
| variations | number | Variation cards (non-parallel) |
| parallels | number | Total parallel card instances |

### Parallels Object

| Field | Type | Description |
|-------|------|-------------|
| total | number | Total number of parallel types |
| fullSet | number | Parallels that apply to entire set |
| partial | number | Parallels that apply to specific cards only |

## Common Use Cases
- Display catalog size on dashboards
- Monitor catalog growth over time
- Provide context about data coverage
- Show breakdown by segment or manufacturer

## Tips for AI Assistants
- This is a public endpoint - no API key required for basic access
- Statistics are cached and updated periodically
- Use this to give users context about the size and scope of the catalog
- The numbers can be formatted with `toLocaleString()` for readability
- Segment breakdown uses `count`, manufacturer breakdown uses `releaseCount`
- Release breakdown uses `byYear` array with `{year, count}` objects
- `sets.identifiable` shows how many sets the AI can recognize from images