loterias-api 1.0.0
Official Python SDK for Loterias API
Requires Python: >=3.8
Keywords: loterias loteria lottery spain euromillones primitiva bonoloto api sdk

# loteria-api

Official Python SDK for [Loteria API](https://loteria-api.com).

## Installation

```bash
pip install loteria-api
```

## Quick Start

```python
from loteria_api import LoteriaApi

api = LoteriaApi(api_key='lat_xxx...')  # Get your API key at https://loteria-api.com

# Get latest Euromillones result
result = api.results.get_latest('euromillones')
print(result['data']['combination'])  # [4, 15, 23, 38, 42]
print(result['data']['resultData']['estrellas'])  # [3, 9]
```

## Usage Examples

### Get Latest Results

```python
# Latest result for a specific game
euromillones = api.results.get_latest('euromillones')
primitiva = api.results.get_latest('primitiva')
bonoloto = api.results.get_latest('bonoloto')

# Latest results for ALL games
all_results = api.results.get_latest_all()
print(all_results['data']['euromillones']['combination'])
print(all_results['data']['primitiva']['combination'])
```

### Check Your Numbers

```python
result = api.results.check_numbers(
    'euromillones',
    numbers=[4, 15, 23, 38, 42],
    extra_numbers=[3, 11]  # Stars for Euromillones
)

if result['data']['isWinner']:
    print(f"You won! Prize: {result['data']['prize']['formattedPrize']}")
    print(f"Category: {result['data']['prize']['categoryName']}")
else:
    print(f"No luck. You matched {result['data']['mainNumbersMatched']} numbers.")
```

### Query Historical Results

```python
# Results from a date range
results = api.results.get_by_date_range(
    'euromillones',
    from_date='2024-01-01',
    to_date='2024-12-31',
    page=1,
    limit=10
)

# Results from a specific date
date_results = api.results.get_by_date('primitiva', '2024-06-15')

# Filter by minimum jackpot
big_jackpots = api.results.list_by_game(
    'euromillones',
    min_jackpot=100000000,  # 100 million
    year=2024
)
```

### Get Upcoming Draws

```python
# All upcoming draws
upcoming = api.draws.list_upcoming()

# Next draw for each game
next_draws = api.draws.get_next_all()
print(f"Next Euromillones: {next_draws['data']['euromillones']['drawDate']}")
print(f"Jackpot: {next_draws['data']['euromillones']['jackpotFormatted']}")

# Upcoming draws for a specific game
euromillones_draws = api.draws.list_upcoming_by_game('euromillones')
```

## Available Game Types

| Slug | Name |
|------|------|
| `bonoloto` | Bonoloto |
| `euromillones` | Euromillones |
| `primitiva` | La Primitiva |
| `gordo` | El Gordo |
| `nacional` | Loteria Nacional |
| `eurodreams` | EuroDreams |
| `quiniela` | La Quiniela |
| `quinigol` | Quinigol |
| `lototurf` | Lototurf |
| `quintuple` | Quintuple Plus |

You can use string literals or the `GameType` enum:

```python
from loteria_api import GameType

result = api.results.get_latest(GameType.EUROMILLONES)
# or
result = api.results.get_latest('euromillones')
```

## Error Handling

```python
from loteria_api import LoteriaApi, LoteriaApiError

try:
    result = api.results.get_latest('euromillones')
except LoteriaApiError as e:
    print(f"API Error: {e.code}")
    print(f"Message: {e.message}")
    print(f"Status: {e.status_code}")

    if e.code == 'RATE_LIMIT_EXCEEDED':
        # Wait and retry
        pass
    if e.code == 'TOKEN_LIMIT_EXCEEDED':
        # Upgrade plan or wait for reset
        pass
```

## Configuration

```python
api = LoteriaApi(
    api_key='lat_xxx...',                              # Required
    base_url='https://custom.url',                     # Optional (default: https://api.loteria-api.com/api/v1)
    timeout=60                                         # Optional (default: 30 seconds)
)
```

## Requirements

- Python 3.8+
- requests >= 2.25.0

## License

MIT