Foresportia Developer API

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.

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.

DNB and double chance

Additional markets are included when present in the enriched files.

League feeds and usage

Short-term league feeds plus daily, monthly and minute usage tracking.

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"
  ]
}

This is the endpoint used by the mini dashboard to identify the beta account.

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.

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/developers.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.

Mini API usage dashboard

This browser tool only calls `https://api.foresportia.com/v1/me` and `https://api.foresportia.com/v1/me/usage` with the key you enter.

Client—

Email—

Plan—

Status—

Daily—Remaining: —

Monthly—Remaining: —

Minute—Remaining: —

Last used at—

Key—

Available endpoints

Request beta access

The existing beta request form is available on the API interest page. Access is reviewed manually.

Request access No backend form is added on this page.

A future dashboard may let API users access usage and manage keys by receiving a temporary code by email. This page does not implement a fake login, password login or key management flow.

Foresportia Developer API

Built for analytics, not betting advice

What the API provides

1X2 probabilities

Confidence badges

Likely scores

BTTS / Over / Under

DNB and double chance

League feeds and usage

Current beta endpoints

curl

Response example

curl

Response example

curl

Response example

curl

Response example

curl

Response example

curl

Response example

curl

Response example

Common response fields

League matches parameters

Data format

Probabilities

Kickoff times

Confidence badges

Human labels

Authentication and rate limits

beta_free

Limits may evolve

Rows are tracked

Prompt to copy into ChatGPT, Claude or another AI assistant

Mini API usage dashboard

Request beta access

Coming later: email-code login