Metadata-Version: 2.2
Name: foresportia
Version: 0.1.0
Summary: Official Python SDK for the Foresportia API
Author-email: Quentin Barbedienne <contact@foresportia.com>
License: MIT
Project-URL: Homepage, https://www.foresportia.com
Project-URL: Documentation, https://www.foresportia.com/en/developers.html
Project-URL: Dashboard, https://www.foresportia.com/en/api-dashboard.html
Project-URL: Repository, https://github.com/QBarbedienne/foresportia-python
Project-URL: Issues, https://github.com/QBarbedienne/foresportia-python/issues
Keywords: foresportia,football,soccer,analytics,api,sdk
Classifier: Development Status :: 4 - Beta
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: respx; extra == "dev"
Requires-Dist: twine; extra == "dev"

# Foresportia Python SDK

Python SDK for the Foresportia API, a private beta football analytics API that
provides match data, model probabilities, predicted picks, confidence signals,
and related football prediction data.

> **Beta warning**
>
> This SDK and the Foresportia API are currently in private beta. Access is
> limited to selected beta users, and endpoints, response fields, limits, and
> model outputs may change before a stable release.

## What Foresportia API Is

The Foresportia API gives developers programmatic access to football match
analytics generated by Foresportia. It is designed for products and internal
tools that need structured match information, model probabilities, and cautious
prediction metadata.

Foresportia provides probabilities and analytics only. It does not provide
bookmaker odds, wagering instructions, or betting advice.

## What You Can Build

With the Python SDK, beta users can build:

- Internal dashboards for upcoming football matches and model outputs.
- Match monitoring workflows that export daily predictions to CSV or BI tools.
- Research notebooks that compare probabilities across leagues and dates.
- Lightweight backend jobs that fetch daily picks or league-specific match data.
- User-facing football analytics features, subject to your beta access terms.

## Data Available Through the API

Depending on endpoint access and match availability, API responses may include:

- Match identifiers, teams, league metadata, dates, and kickoff times.
- Home, draw, and away probabilities.
- A predicted pick or model-preferred outcome.
- Confidence, stability, or similar quality indicators.
- Likely score information when available.
- Account and usage information for the current API key.

Response schemas may evolve during beta. Client code should read optional fields
defensively with `.get()`.

## Installation

Install the package from PyPI:

```bash
pip install foresportia
```

For local development from a cloned repository:

```bash
pip install -e ".[dev]"
```

The Foresportia API itself remains in private beta, so installing the SDK does
not grant API access automatically.

## Get Beta Access

The Foresportia API is currently in private beta. To request access, see the
developer documentation:

- English docs: https://www.foresportia.com/en/developers.html
- French docs: https://www.foresportia.com/developpeurs.html

## Authentication

Foresportia API access is granted manually during the private beta. After access
is approved, you receive an API key.

Set the key in the `FORES_API_KEY` environment variable:

```bash
export FORES_API_KEY="fs_beta_your_key_here"
```

On PowerShell:

```powershell
$env:FORES_API_KEY = "fs_beta_your_key_here"
```

The SDK sends the key in the `X-API-Key` header. It does not put the key in the
request URL.

## API Key

Once your access is enabled, you can use the API dashboard to monitor usage,
view active key prefixes, and generate a new key if needed:

- English dashboard: https://www.foresportia.com/en/api-dashboard.html
- French dashboard: https://www.foresportia.com/api-dashboard.html

Do not commit API keys to source control, notebooks, screenshots, or support
tickets.

## Quick Start

```python
from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    account = client.me()
    picks = client.picks_today()

print(account.get("plan"))
print(f"Matches returned: {len(picks.get('matches', []))}")
```

## Common Examples

### Print Today's Picks

```python
from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    data = client.picks_today()

for match in data.get("matches", []):
    home_team = match.get("home_team", "Home")
    away_team = match.get("away_team", "Away")
    pick = match.get("pick") or match.get("predicted_pick") or "n/a"
    print(f"{home_team} vs {away_team}: {pick}")
```

See
[examples/print_today_picks.py](https://github.com/QBarbedienne/foresportia-python/blob/main/examples/print_today_picks.py),
[examples/export_today_picks_to_csv.py](https://github.com/QBarbedienne/foresportia-python/blob/main/examples/export_today_picks_to_csv.py),
and
[examples/filter_high_confidence_matches.py](https://github.com/QBarbedienne/foresportia-python/blob/main/examples/filter_high_confidence_matches.py)
for runnable scripts.

### Check Account

```python
from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    account = client.me()

client_info = account.get("client", {})
print(client_info.get("email"))
print(account.get("plan"))
```

### World Cup 2026 Example

```python
from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    data = client.world_cup_2026_matches(limit=10)

for match in data.get("matches", []):
    print(match.get("home_team"), "vs", match.get("away_team"), "-", match.get("pick"))
```

### League Matches Example

```python
from foresportia import ForesportiaClient

with ForesportiaClient.from_env() as client:
    data = client.league_matches("CHN", include="all", days=14, limit=10)

for match in data.get("matches", []):
    print(match.get("home_team"), "vs", match.get("away_team"), "-", match.get("pick"))
```

## Error Handling

The SDK raises typed exceptions for configuration, authentication,
authorization, rate limiting, transport, API, and response parsing errors.

```python
from foresportia import (
    ForesportiaAPIError,
    ForesportiaAuthError,
    ForesportiaClient,
    ForesportiaConfigurationError,
    ForesportiaRateLimitError,
)

try:
    with ForesportiaClient.from_env() as client:
        data = client.picks_today()
except ForesportiaConfigurationError as exc:
    print(f"Configuration error: {exc}")
except ForesportiaAuthError as exc:
    print(f"Authentication or authorization error: {exc}")
except ForesportiaRateLimitError as exc:
    print(f"Rate limit exceeded: {exc}")
except ForesportiaAPIError as exc:
    print(f"API error on {exc.endpoint}: {exc.status_code}")
```

## Available Methods

```python
client.me()
client.usage()
client.picks_today()
client.matches_today()
client.leagues()
client.league_matches("CHN", include="all", days=14, limit=10)
client.world_cup_2026_matches(limit=10)
```

Method notes:

- `me()` returns account details for the current API key.
- `usage()` returns usage information for the current API key.
- `picks_today()` returns today's Foresportia picks.
- `matches_today()` returns today's matches.
- `leagues()` returns available football leagues.
- `league_matches(...)` returns matches for a league code.
- `world_cup_2026_matches(...)` is a convenience wrapper for the World Cup 2026
  league code.

## Beta Stability Policy

During private beta, Foresportia aims to keep the SDK simple and transparent,
but the API is not yet covered by a stable compatibility guarantee.

- Patch and beta releases may adjust response fields as the API matures.
- Method names in this SDK are intended to remain stable where practical.
- New fields may be added without a major version change.
- Existing fields may be renamed, removed, or made optional before a stable
  release if the beta API changes.
- Production users should pin SDK versions and handle missing response fields.

## Current Limitations

- The API is currently available only to selected beta users.
- Endpoints and response schemas may evolve before a stable release.
- The SDK currently provides a synchronous client only.
- The SDK returns API responses as dictionaries rather than typed models.
- Bookmaker odds are not included.
- Historical coverage, league availability, limits, and refresh timing may vary
  during beta.

## Language

This README is written in English for the Python developer ecosystem. French
documentation is also available:

https://www.foresportia.com/developpeurs.html

## Links

- Homepage: https://www.foresportia.com
- Developer docs (EN): https://www.foresportia.com/en/developers.html
- Developer docs (FR): https://www.foresportia.com/developpeurs.html
- API dashboard (EN): https://www.foresportia.com/en/api-dashboard.html
- API dashboard (FR): https://www.foresportia.com/api-dashboard.html
- Getting started: https://github.com/QBarbedienne/foresportia-python/blob/main/docs/getting-started.md
- Authentication: https://github.com/QBarbedienne/foresportia-python/blob/main/docs/authentication.md
- Response fields: https://github.com/QBarbedienne/foresportia-python/blob/main/docs/response-fields.md
- Examples: https://github.com/QBarbedienne/foresportia-python/blob/main/docs/examples.md
- Beta limitations: https://github.com/QBarbedienne/foresportia-python/blob/main/docs/beta-limitations.md

## Disclaimer

Foresportia provides football probabilities, model outputs, and analytics data.
It does not provide betting advice, financial advice, bookmaker odds, guaranteed
outcomes, or instructions to place wagers. Any use of Foresportia data is the
responsibility of the user and should comply with applicable laws, regulations,
and platform policies.

## License

MIT. See
[LICENSE](https://github.com/QBarbedienne/foresportia-python/blob/main/LICENSE).
