Foresportia API for developers

Official Python SDK

The Foresportia API now has an official Python SDK available on PyPI. It lets beta users call the API from scripts, notebooks or backend jobs without manually writing HTTP requests. API access remains subject to private beta approval: installing the package does not grant access automatically.

Python developers can use the official Foresportia Python SDK documentation

pip install foresportia

from foresportia import ForesportiaClient

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

print(len(picks.get("matches", [])))

The SDK reads `FORES_API_KEY` from the environment and sends it through the `X-API-Key` header. Links: PyPI package · GitHub repository.

Built for analytics, not betting advice

The API is for sports analytics, dashboards, private tools, bots, research and backtesting.

It is not betting advice and it does not guarantee results. Automated betting, resale of raw data or public mirroring is not allowed without explicit permission.

Research reference

For the confidence layer behind probability distributions, see the May 2026 paper Beyond Top Probability: Shannon Entropy as a Confidence Signal in Football Forecasting.

What the API provides

The private beta exposes a stable external schema, separate from the website endpoints.

1X2 probabilities

Home, draw and away probabilities as ratios between 0 and 1.

Confidence badges

Machine badges and readable labels for match stability.

Likely scores

Structured likely score candidates when available.

BTTS / Over / Under

Goal markets exposed as clean ratio fields.

Context signals

Rankings, availability and contextual indicators when they are reliable enough to expose.

League-level data

Short-term feeds by league, match and date depending on the beta scope available.

Use cases

The API is intended for serious football data integrations that need structured signals, not outcome promises.

Football dashboards

Track probabilities, goal markets and stability badges.

Telegram / Discord bots

Publish match readings or private alerts based on your own criteria.

Python notebooks

Explore Foresportia signals with pandas, notebooks or research scripts.

Match previews

Enrich editorial analysis with probabilities, context and goal trends.

Media / data analysis tools

Compare leagues, filter matches and prepare data-driven content formats.

Current beta endpoints

Each endpoint below includes a short description, auth mode, static curl example and compact response example. Protected examples use `YOUR_API_KEY` as a placeholder.

GET /v1/healthPublic

Public health check for the v1 API layer.

curl

curl https://api.foresportia.com/v1/health

Response example

{
  "status": "ok",
  "api_version": "v1",
  "source": "Foresportia"
}

Use this endpoint to check that the public API layer is reachable.

GET /v1/meX-API-Key required

Returns account status, plan, client info and available endpoints for the current API key.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/me

Response example

{
  "status": "active",
  "plan": "beta_free",
  "client": {
    "name": "Example User",
    "email": "user@example.com",
    "usage_type": "dashboard"
  },
  "endpoints": [
    "GET /v1/health",
    "GET /v1/me",
    "GET /v1/me/usage",
    "GET /v1/leagues",
    "GET /v1/leagues/{league_code}/matches",
    "GET /v1/picks/today",
    "GET /v1/matches/today"
  ]
}

Use this endpoint to identify the beta account associated with the API key from a server or private tool.

GET /v1/me/usageX-API-Key required

Returns daily, monthly and per-minute usage for the current API key.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/me/usage

Response example

{
  "daily": {
    "date": "2026-05-20",
    "used": 17,
    "limit": 100,
    "remaining": 83
  },
  "monthly": {
    "month": "2026-05",
    "used": 177,
    "limit": 2000,
    "remaining": 1823
  },
  "rate_limit_minute": {
    "used": 2,
    "limit": 10,
    "remaining": 8
  },
  "last_used_at": "2026-05-20T09:20:25Z"
}

Rows returned are also tracked internally for operational monitoring.

GET /v1/picks/todayX-API-Key required

Returns selected picks for the current day. This is a curated subset, not every available match.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/picks/today

Response example

{
  "date": "2026-05-20",
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "0f5f178951689210",
      "kickoff": "2026-05-20T18:00:00Z",
      "kickoff_local": "2026-05-20T20:00:00+02:00",
      "league": {
        "code": "NOR",
        "name": "Eliteserien",
        "country": "Norway"
      },
      "home_team": "IK Start",
      "away_team": "FK Bodø/Glimt",
      "probabilities": {
        "home": 0.0844,
        "draw": 0.1712,
        "away": 0.7445
      },
      "confidence": {
        "badge": "ultra_stable",
        "label": "Very stable",
        "score": 0.773469
      },
      "likely_scores": [
        {
          "score": "1-1",
          "probability": 0.1234
        },
        {
          "score": "0-1",
          "probability": 0.1033
        }
      ],
      "markets": {
        "btts": 0.5539,
        "over_2_5": 0.6685,
        "under_2_5": 0.3315
      },
      "status": "scheduled",
      "pick": {
        "outcome": "away",
        "probability": 0.7445
      }
    }
  ]
}

Probabilities and market values are ratios between 0 and 1.

GET /v1/matches/todayX-API-Key required

Returns all matches available for today in the external v1 format. The match object is similar to `/v1/picks/today`, but the endpoint is not limited to selected picks.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/matches/today

Response example

{
  "date": "2026-05-20",
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "43636da1c3e70181",
      "kickoff": "2026-05-20T13:35:00Z",
      "kickoff_local": "2026-05-20T15:35:00+02:00",
      "league": {
        "code": "CHN",
        "name": "Chinese Super League",
        "country": "China"
      },
      "home_team": "Shanghai Shenhua",
      "away_team": "Wuhan Three Towns",
      "probabilities": {
        "home": 0.6624,
        "draw": 0.2206,
        "away": 0.117
      },
      "confidence": {
        "badge": "correct",
        "label": "Correct",
        "score": 0.73624
      },
      "markets": {
        "btts": 0.5425,
        "over_2_5": 0.5955,
        "under_2_5": 0.4045
      },
      "status": "scheduled",
      "pick": {
        "outcome": "home",
        "probability": 0.6624
      }
    }
  ]
}

Use this endpoint when you need the full daily feed rather than only selected picks.

GET /v1/leaguesX-API-Key required

Returns available league codes and metadata for the short-term enriched feeds.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/leagues

Response example

{
  "source": "Foresportia",
  "data_version": "example",
  "leagues": [
    {
      "code": "CHN",
      "name": "Chinese Super League",
      "country": "China",
      "available": true,
      "matches_available": 24
    },
    {
      "code": "NOR",
      "name": "Eliteserien",
      "country": "Norway",
      "available": true,
      "matches_available": 8
    }
  ]
}

Use these codes in `/v1/leagues/{league_code}/matches`.

GET /v1/leagues/{league_code}/matchesX-API-Key required

Returns a bounded short-term league feed. This endpoint supports upcoming, recent past or mixed windows.

curl

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.foresportia.com/v1/leagues/CHN/matches?include=all&days=14&limit=20"

Response example

{
  "league": {
    "code": "CHN",
    "name": "Chinese Super League",
    "country": "China"
  },
  "date_range": {
    "start": "2026-05-20",
    "end": "2026-06-02",
    "include": "all"
  },
  "timezone": "Europe/Paris",
  "source": "Foresportia",
  "data_version": "example",
  "matches": [
    {
      "id": "43636da1c3e70181",
      "kickoff": "2026-05-20T13:35:00Z",
      "kickoff_local": "2026-05-20T15:35:00+02:00",
      "league": {
        "code": "CHN",
        "name": "Chinese Super League",
        "country": "China"
      },
      "home_team": "Shanghai Shenhua",
      "away_team": "Wuhan Three Towns",
      "probabilities": {
        "home": 0.6624,
        "draw": 0.2206,
        "away": 0.117
      },
      "confidence": {
        "badge": "correct",
        "label": "Correct",
        "score": 0.73624
      },
      "markets": {
        "btts": 0.5425,
        "over_1_5": 0.9352,
        "over_2_5": 0.5955,
        "over_3_5": 0.6444,
        "under_1_5": 0.0648,
        "under_2_5": 0.4045,
        "under_3_5": 0.3556,
        "dnb_home": 0.8499,
        "dnb_away": 0.1501,
        "double_chance_1x": 0.883,
        "double_chance_x2": 0.3376,
        "double_chance_12": 0.7794
      },
      "ranking": {
        "home_rank": 9,
        "away_rank": 15,
        "home_context_rank": 3,
        "away_context_rank": 14,
        "source": "api_standings",
        "is_reliable": true
      },
      "status": "scheduled",
      "pick": {
        "outcome": "home",
        "probability": 0.6624
      }
    }
  ]
}

This is not a full historical export. Past data here is limited to recent rows present in the enriched league files.

Common response fields

probabilities.home/draw/away	1X2 probabilities as ratios between 0 and 1.
markets.*	Market probabilities as ratios between 0 and 1.
kickoff	UTC ISO-8601 datetime.
kickoff_local	Datetime converted to the API timezone, currently Europe/Paris.
confidence.badge	Machine value: `ultra_stable`, `stable`, `correct` or `risk`.
confidence.label	Human-readable label such as `Very stable`, `Stable`, `Correct` or `Risk`.
pick.outcome	Predicted 1X2 side: `home`, `draw` or `away`.
likely_scores.probability	Estimated exact score probability when available.
ranking	Included only when ranking data is available and reliable enough to expose.

League matches parameters

include	`upcoming`, `past` or `all`. Default: `upcoming`.
start	Optional `YYYY-MM-DD` start date.
days	Window size from `start`, between 1 and 31 days.
limit	Maximum rows returned, between 1 and 500.

`upcoming` returns upcoming matches only. `past` returns recent past matches available in the short-term enriched files. `all` returns both past and upcoming matches inside the selected window. This is not a full historical export.

Data format

Probabilities

Probabilities are ratios between 0 and 1. Example: `0.7445` means `74.45%`.

Kickoff times

`kickoff` is UTC. `kickoff_local` is converted to the API timezone, currently Europe/Paris.

Confidence badges

`ultra_stable`, `stable`, `correct`, `risk` are machine-readable badge values.

Human labels

`Very stable`, `Stable`, `Correct`, `Risk` are provided in `confidence.label`.

Authentication and rate limits

Use the `X-API-Key` header. API keys are private and must not be exposed in public frontend code or GitHub repositories. Call the API from a backend, script, bot or private environment.

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.foresportia.com/v1/picks/today

beta_free

100 requests/day, 2000 requests/month, 10 requests/minute.

Limits may evolve

Private beta quotas can change as usage patterns become clearer.

Rows are tracked

Rows returned are also tracked internally for operational visibility.

Error handling

All endpoints return standard HTTP status codes. Error responses are JSON with a short message field.

200 OK	Request succeeded.
400 Bad Request	Invalid query parameter (for example unknown `league_code` or out-of-range `days`/`limit`).
401 Unauthorized	Missing or invalid `X-API-Key` header.
403 Forbidden	API key not allowed to call this endpoint or beta access not yet activated.
404 Not Found	Resource not found (for example unknown league code).
429 Too Many Requests	Per-minute, daily or monthly rate limit exceeded. Retry after the limit window resets.
5xx Server Error	Temporary backend issue. Retry with exponential backoff.

Client code should treat unknown 5xx responses as transient and not as definitive failures.

Prompt to copy into ChatGPT, Claude or another AI assistant

Use this prompt to ask an AI assistant to help you integrate the API. If your AI assistant has web access, it can read this page. Only paste a real API key into a private environment you are comfortable using with that AI tool; otherwise, keep the key in an environment variable.

You are my technical assistant. Help me use the private beta Foresportia API.

First, read the public documentation:
https://www.foresportia.com/en/api.html

Goal:
- call the Foresportia API from a script or backend, not from public frontend JavaScript;
- use the X-API-Key header;
- keep my API key in an environment variable named FORES_API_KEY;
- never print, log or commit the API key;
- use the relevant endpoints for my need: /v1/me, /v1/me/usage, /v1/picks/today, /v1/matches/today, /v1/leagues, /v1/leagues/{league_code}/matches;
- respect beta rate limits and handle 401, 429 and network errors.

Important context:
- Probabilities and markets are ratios between 0 and 1.
- kickoff is UTC and kickoff_local is in the API timezone.
- Foresportia provides football analytics data and model probabilities. It is not betting advice and does not guarantee any result.

Start by proposing a simple and safe implementation in this language: [Python / Node.js / other].
Use YOUR_API_KEY only as a placeholder in examples.

Tip: only replace the preferred language. For real usage, store the key in `FORES_API_KEY` on a backend or private local environment.

Connected API dashboard

Usage, active keys and key rotation are now separated from this public documentation.

Already have API access? Open the API dashboard

Passwordless sign-in with email and a temporary code. Existing keys are never shown in full.

Open the API dashboard

Request beta access

The existing beta request form is available on the API interest page. Access is reviewed manually. You can also email contact@foresportia.com with a short description of your project.

Request access No backend form is added on this page.