OpenFootAPI

https://openfootapi.com/docs
Admin
OpenFootAPI is a REST API that provides football fixtures, live match events, confirmed lineups,...
Tokens:3,725
Snippets:26
Trust Score:2.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /v1/matches with demo key

Source: https://openfootapi.com/docs

Make a GET request to /v1/matches with the demo key to retrieve scheduled matches for a given date. The response is a 200 OK with an abridged JSON object containing match data and metadata. Use this to test the API without an account.

```bash
curl "https://openfootapi.com/v1/matches?date=2026-08-28" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer of_demo_openfootapi_docs"
```

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

--------------------------------

### Fetch live and scheduled matches with TypeScript

Source: https://openfootapi.com/docs

Use this TypeScript/Node.js fetch example to call the live and scheduled matches endpoint. It sends a GET request to `/v1/matches?date=2026-08-28&status=scheduled`, handles non-OK responses by extracting the error message, and logs the `data` field on success.

```typescript
const url = "https://openfootapi.com/v1/matches?date=2026-08-28&status=scheduled";
const headers: Record<string, string> = {
  "Accept": "application/json",
  
};

async function fetchFootballData() {
  try {
    const response = await fetch(url, { headers });
    if (!response.ok) {
      const err = await response.json();
      throw new Error(err.error?.message || `HTTP ${response.status}`);
    }
    
    const payload = await response.json();
    console.log("Success:", payload.data);
    return payload.data;
  } catch (error) {
    console.error("API Request Error:", error);
  }
}

fetchFootballData();
```

--------------------------------

### GET /v1/matches

Source: https://openfootapi.com/docs

Retrieves football fixtures and results for a given date. This endpoint is part of the OpenFootAPI REST interface and requires no key to start testing with the demo key.

```APIDOC
## GET /v1/matches

### Description
Retrieves football fixtures and results for a given date. This endpoint is part of the OpenFootAPI REST interface and requires no key to start testing with the demo key.

### Method
GET

### Endpoint
/v1/matches

### Parameters
#### Query Parameters
- **date** (string) - Required - The date for which to retrieve matches, in YYYY-MM-DD format.

### Request Example
```
curl "https://openfootapi.com/v1/matches?date=2026-08-28" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer of_demo_openfootapi_docs"
```

### Response
#### Success Response (200)
- **data** (array) - List of match objects.
- **data.id** (string) - Unique identifier for the match.
- **data.competitionId** (string) - Identifier for the competition.
- **data.status** (string) - Status of the match (e.g., scheduled).
- **data.kickoffAt** (string) - Kickoff time in ISO 8601 format.
- **data.homeTeam** (object) - Home team information.
- **data.homeTeam.id** (string) - Home team identifier.
- **data.homeTeam.name** (string) - Home team name.
- **data.awayTeam** (object) - Away team information.
- **data.awayTeam.name** (string) - Away team name.
- **meta** (object) - Metadata about the response.
- **meta.count** (number) - Number of matches returned.
- **meta.environment** (string) - Environment (e.g., beta).
- **meta.access** (object) - Access information.
- **meta.access.authenticated** (boolean) - Whether the request was authenticated.
- **meta.access.plan** (string) - Access plan (e.g., public).

#### Response Example
```
{
  "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" }
  }
}
```
```

--------------------------------

### GET /v1/matches

Source: https://openfootapi.com/docs

Retrieve fixtures across 120+ global competitions with live scores and venue data. Supports filtering by date, competition, team, status, and season.

```APIDOC
## GET /v1/matches

### Description
Retrieve fixtures across 120+ global competitions with live scores and venue data. Filters can be combined. Dates are interpreted as UTC calendar dates and entity filters use stable OpenFootAPI IDs returned by search.

### Method
GET

### Endpoint
/v1/matches

### Parameters
#### Query Parameters
- **date** (date) - Optional - Kickoff date in YYYY-MM-DD.
- **competition** (string) - Optional - Stable OpenFootAPI competition ID.
- **team** (string) - Optional - Stable OpenFootAPI team ID.
- **status** (enum) - Optional - scheduled, live, finished or postponed.
- **season** (string) - Optional - Season label such as 2026/27.

### Request Example
```
GET /v1/matches?date=2026-08-28&status=scheduled
```

### Response
#### Success Response (200)
- **data** - The requested resource. An object or array with normalized field types.
- **meta** - How the response was produced. Request ID, generation time, access tier, sources and count.

#### Response Example
```json
{
  "data": {},
  "meta": {}
}
```

### Error Responses
- **400** - Invalid filters
- **401** - Invalid API key
- **403** - Plan restriction
- **404** - Resource missing
- **429** - Quota exhausted
- **502** - Source unavailable
```

--------------------------------

### GET /v1/matches/{match_id}/context

Source: https://openfootapi.com/docs

Compute an integration-ready snapshot from available match history, tactical models and live streams. Provides match context and intelligence including form, Elo ratings, expected goals, odds benchmark, momentum, and head-to-head history.

```APIDOC
## GET /v1/matches/{match_id}/context

### Description
Compute an integration-ready snapshot from available match history, tactical models and live streams. Provides match context and intelligence including form, Elo ratings, expected goals, odds benchmark, momentum, and head-to-head history.

### Method
GET

### Endpoint
/v1/matches/{match_id}/context

### Parameters
#### Path Parameters
- **match_id** (string) - Required - The stable OpenFootAPI match ID.

### Response
#### Success Response (200)
- **home.form** - Up to five completed matches
- **home.elo** - Derived strength rating
- **analytics.expectedGoals** - xG models and goal expectancy
- **analytics.oddsBenchmark** - Projected fair odds & win percentages
- **analytics.momentum** - Attack pressure index and fatigue risk
- **headToHead** - Available previous meetings

#### Response Example
```json
{
  "data": {
    "home": {
      "form": [],
      "elo": 0
    },
    "analytics": {
      "expectedGoals": {},
      "oddsBenchmark": {},
      "momentum": {}
    },
    "headToHead": []
  },
  "meta": {}
}
```

### Error Responses
- **400** - Invalid filters
- **401** - Invalid API key
- **403** - Plan restriction
- **404** - Resource missing
- **429** - Quota exhausted
- **502** - Source unavailable
```

--------------------------------

### GET match context endpoint

Source: https://openfootapi.com/docs

This is the public-preview endpoint for match context. It returns a JSON response with match details and analytics. Use it to inspect the live API response without a developer key.

```http
GET`/v1/matches/match_olg_83156/context`
```

--------------------------------

### Bearer API key header

Source: https://openfootapi.com/docs

Use this header to authenticate every endpoint with your own API key. Raw keys start with `of_live_`; OpenFootAPI stores only a SHA-256 hash. Replace `of_live_your_api_key` with your actual key.

```http
Authorization: Bearer of_live_your_api_key
```
Tokens:
Raw