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.
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.
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.
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().
Install the package from PyPI:
pip install foresportiaFor 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.
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
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.
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.
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', []))}")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.
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"))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"))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"))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}")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.
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.
- 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.
This README is written in English for the Python developer ecosystem. French documentation is also available:
https://www.foresportia.com/developpeurs.html
- 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
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.
MIT. See LICENSE.