Metadata-Version: 2.1
Name: slot-data-api
Version: 1.0.0
Summary: Python client for the slot.report Slot Data API. Access 5,600+ online slot games with RTP, volatility, max win, features, mechanics and themes.
Author: slot.report
License: MIT
Project-URL: Homepage, https://slot.report/
Project-URL: Documentation, https://slot.report/api/
Project-URL: Repository, https://github.com/slotreport/slot-data-api-python
Keywords: slots,casino,igaming,rtp,volatility,game-data,api-client
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx

# slot-data-api

Python client for the [slot.report](https://slot.report/) Slot Data API.

Access **5,600+ online slot games** with RTP, volatility, max win, features, mechanics and themes. Free, no API key required.

## Installation

```bash
pip install slot-data-api
```

## Quick Start

```python
from slot_data_api import SlotAPI

api = SlotAPI()

# Get API status
status = api.get_status()
print(f"Total slots: {status['total_slots']}")
print(f"Total providers: {status['total_providers']}")

# List all slots (cached after first call)
slots = api.get_slots()
print(f"Loaded {len(slots)} slots")

# Get a single slot with full details
slot = api.get_slot("gates-of-olympus")
print(f"{slot['name']} — RTP: {slot['rtp']}%, Max Win: {slot['max_win']}x")

# List all providers
providers = api.get_providers()
for p in providers[:5]:
    print(f"{p['name']}: {p['total_slots']} slots, avg RTP {p['avg_rtp']}%")

# Get all slots from a provider
pp = api.get_provider_slots("pragmatic-play")
print(f"Pragmatic Play: {pp['count']} slots")
```

## Search & Filter

```python
# Search by name
results = api.search("olympus")
print(f"Found {len(results)} slots matching 'olympus'")

# Filter by multiple criteria
high_rtp = api.filter(
    provider="pragmatic-play",
    volatility="high",
    min_rtp=96.0,
    min_max_win=5000,
)
for s in high_rtp[:5]:
    print(f"{s['name']} — RTP: {s['rtp']}%, Max Win: {s['max_win']}x")

# Filter by feature, mechanic, or theme
wilds = api.filter(feature="wild")
megaways = api.filter(mechanic="megaways")
egyptian = api.filter(theme="egypt")
```

## API Reference

### `SlotAPI(base_url, timeout)`

Create a client instance.

| Parameter  | Default                          | Description         |
|------------|----------------------------------|---------------------|
| `base_url` | `https://slot.report/api/v1`     | API base URL        |
| `timeout`  | `30.0`                           | Request timeout (s) |

### Methods

| Method                     | Returns       | Description                              |
|----------------------------|---------------|------------------------------------------|
| `get_status()`             | `dict`        | API status, coverage stats               |
| `get_slots()`              | `list[dict]`  | All slots (cached after first call)      |
| `get_slot(slug)`           | `dict`        | Single slot with full details            |
| `get_providers()`          | `list[dict]`  | All providers                            |
| `get_provider_slots(slug)` | `dict`        | Provider info + slots list               |
| `search(query)`            | `list[dict]`  | Search slots by name                     |
| `filter(...)`              | `list[dict]`  | Filter slots by criteria                 |
| `clear_cache()`            | `None`        | Clear cached slot list                   |

### `filter()` Parameters

All parameters are optional and combined with AND logic.

| Parameter     | Type    | Description                                  |
|---------------|---------|----------------------------------------------|
| `provider`    | `str`   | Provider slug (e.g. `"pragmatic-play"`)      |
| `volatility`  | `str`   | Volatility level (e.g. `"high"`, `"extreme"`)|
| `min_rtp`     | `float` | Minimum RTP (inclusive)                      |
| `max_rtp`     | `float` | Maximum RTP (inclusive)                      |
| `min_max_win` | `float` | Minimum max-win multiplier (inclusive)       |
| `feature`     | `str`   | Feature name (case-insensitive match)        |
| `mechanic`    | `str`   | Mechanic name (case-insensitive match)       |
| `theme`       | `str`   | Theme name (case-insensitive match)          |

## Slot Object Fields

| Field              | Type         | Description                          |
|--------------------|--------------|--------------------------------------|
| `name`             | `str`        | Game name                            |
| `slug`             | `str`        | URL slug                             |
| `provider`         | `str`        | Provider name                        |
| `provider_slug`    | `str`        | Provider URL slug                    |
| `rtp`              | `float/null` | Return to Player percentage          |
| `volatility`       | `str/null`   | Volatility level                     |
| `volatility_score` | `int/null`   | Volatility as number (1-5)           |
| `max_win`          | `float/null` | Maximum win multiplier               |
| `max_win_category` | `str/null`   | Max win tier (low/medium/high/very-high) |
| `has_bonus_buy`    | `bool/null`  | Bonus buy available                  |
| `grid`             | `str/null`   | Grid layout (e.g. "5x3")            |
| `release_date`     | `str/null`   | Release date                         |
| `year`             | `int/null`   | Release year                         |
| `features`         | `list[str]`  | Game features                        |
| `mechanic`         | `str/null`   | Game mechanic                        |
| `theme`            | `str/list`   | Theme(s)                             |
| `paylines`         | `int/null`   | Number of paylines                   |
| `min_bet`          | `float/null` | Minimum bet                          |
| `max_bet`          | `float/null` | Maximum bet                          |
| `hit_frequency`    | `float/null` | Hit frequency percentage             |

The single-slot endpoint (`get_slot()`) returns additional fields: `summary`, `score`, `bonus_buy_prices`, `rtp_tiers`, `series`, and `free_spins`.

## Data Source

All data provided by [slot.report](https://slot.report/). Free to use — please credit slot.report as data source.

## License

MIT
