foresportia 0.1.0

Official Python SDK for the Foresportia API

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:

pip install foresportia

For local development from a cloned repository:

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:

export FORES_API_KEY="fs_beta_your_key_here"

On 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

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

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, examples/export_today_picks_to_csv.py, and examples/filter_high_confidence_matches.py for runnable scripts.

Check Account

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

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

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.

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

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.