OPEN DATA BETA · v1

FootballStack API documentation

Build with normalized fixtures, results, competitions, stable entity IDs and derived match context. Responses use the same data, meta and error contract.

Real dataThe beta reads OpenLigaDB for current German competitions and OpenFootball for four league archives. It does not include lineups, player events or an uptime SLA.

01 · Quickstart

Your first request

The public preview works without a key and returns up to five matches per request.

cURLGET /v1/matches

curl "https://footballstack-api.netrebnic.chatgpt.site/v1/matches?date=2026-08-28" \
  -H "Accept: application/json"

Response

200 OKabridged JSON

{
  "data": [
    {
      "id": "match_olg_83156",
      "competitionId": "comp_bundesliga_de",
      "status": "scheduled",
      "kickoffAt": "2026-08-28T18:30:00.000Z",
      "homeTeam": { "id": "team_olg_40", "name": "FC Bayern München" },
      "awayTeam": { "name": "VfB Stuttgart" }
    }
  ],
  "meta": {
    "count": 1,
    "environment": "beta",
    "access": { "authenticated": false, "plan": "public" }
  }
}

02 · Authentication

Bearer API keys

A Founding Beta key unlocks the full result set, every match-context ID and 10,000 measured requests per month. Raw keys start with fs_live_; FootballStack stores only a SHA-256 hash.

Authorization: Bearer fs_live_your_api_key

Public previewUnauthenticated match and search results are capped at five items. Match context without a key is limited to match_olg_83156.

03 · Sources and coverage

What is actually available

NOWOpenLigaDB · ODbL-1.0

Bundesliga, 2. Bundesliga and DFB Pokal

Current and previous-season fixtures/results. Standings, form, Elo, rest and head-to-head are derived where sufficient league history exists.

ARCOpenFootball · CC0-1.0

Four league archives

Premier League, La Liga, Serie A and Ligue 1 season files. These are archives, not a live feed.

Every relevant response includes source and license metadata. If you publicly redistribute an adapted OpenLigaDB database, review the ODbL attribution and share-alike requirements for your use case.

04 · API reference

Endpoints

GET/v1/health

API health

Current service, API version and active provider state.

GET/v1/competitions

Competitions

Coverage flags, seasons, source and license for each competition.

GET/v1/matches

Matches

Fixtures and results filtered by date, competition, team, status or season.

GET/v1/matches/{id}/context

Match context

Derived form, Elo, rest, table position, venue record, head-to-head and freshness.

GET/v1/search?q={query}

Entity search

Resolve team and competition names to stable FootballStack IDs.

05 · Signature endpoint

Match context

The context endpoint computes an integration-ready snapshot from available match history. A field can be empty or null when a new season has not produced enough history.

home.formUp to five completed matches

home.eloDerived strength rating

home.restDaysDays since previous match or null

headToHeadAvailable previous meetings

tablePositionDerived current-season rank or null

freshnessSource update timestamps

06 · Errors

Typed, predictable errors

Errors use stable codes, including invalid_api_key, monthly_quota_exceeded, founding_key_required and source_unavailable.

{ "error": { "code": "founding_key_required", "message": "Use a Founding Beta key for this match context." } }

07 · Try it

Live beta

Run a public-preview endpoint from this deployment and inspect the real JSON response.

Endpoint

GET/v1/matches/match_olg_83156/context

ready

Select an endpoint and run the request.