# Football Data — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Get live match scores, team standings, and player statistics across football competitions worldwide. Search for teams, view head-to-head matchups, track top scorers, and explore detailed information about competitions and geographical areas.

**Category:** Sports | **Website:** [football-data.org/](https://football-data.org/) | **Docs:** [parse.bot/marketplace/0ab7d5b8-b2ff-4373-b0fc-922caab23477/football-data-org-api](https://parse.bot/marketplace/0ab7d5b8-b2ff-4373-b0fc-922caab23477/football-data-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_area

Retrieve details for a specific area by ID. Continent-level areas (e.g. Europe, id 2077) return a populated childAreas list. Country-level areas (e.g. England, id 2072) return an empty childAreas array.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `area_id` | integer | Yes | Area ID (e.g. 2077 for Europe, 2072 for England, 2220 for South America) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_area \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_id":"<integer>"}'
```

### get_competition

Retrieve details for a specific competition by numeric ID or string code. Both formats are interchangeable (e.g. 2021 and 'PL' both return Premier League). Returns competition metadata, current season, and historical seasons list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition ID or code (e.g. '2021' or 'PL' for Premier League, '2001' or 'CL' for Champions League, '2002' or 'BL1' for Bundesliga, '2019' or 'SA' for Serie A, '2014' or 'PD' for La Liga, '2015' or 'FL1' for Ligue 1) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_competition \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>"}'
```

### get_competition_matches

Retrieve all matches for a specific competition. Supports filtering by season, matchday, status, date range (max 10 days), stage, and group. Returns match details including teams, score, and referees.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition ID or code (e.g. '2021' or 'PL' for Premier League, '2001' or 'CL' for Champions League, '2002' or 'BL1' for Bundesliga, '2019' or 'SA' for Serie A) |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD). Date range must not exceed 10 days. |
| `group` | string | No | Group name filter |
| `matchday` | integer | No | Matchday number |
| `season` | integer | No | Season start year (e.g. 2023) |
| `stage` | string | No | Stage filter (e.g. REGULAR_SEASON, GROUP_STAGE) |
| `status` | string | No | Match status: SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, CANCELLED |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_competition_matches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>","date_from":"<string>","date_to":"<string>","group":"<string>","matchday":"<integer>","season":"<integer>","stage":"<string>","status":"<string>"}'
```

### get_competition_scorers

Retrieve top scorers for a competition. Returns current season by default. Each scorer entry includes player details, team, goals, assists, played matches, and penalties.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition ID or code (e.g. '2021' or 'PL') |
| `limit` | integer | No | Maximum number of scorers to return |
| `season` | integer | No | Season start year (e.g. 2023) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_competition_scorers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>","limit":"<integer>","season":"<integer>"}'
```

### get_competition_standings

Retrieve league table/standings for a competition. Returns current season standings by default. Use the season parameter to retrieve historical standings. Each standings entry contains team position, points, wins, draws, losses, and goal statistics.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition ID or code (e.g. '2021' or 'PL') |
| `date` | string | No | Date for standings snapshot (YYYY-MM-DD) |
| `matchday` | integer | No | Matchday number |
| `season` | integer | No | Season start year (e.g. 2023) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_competition_standings \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>","date":"<string>","matchday":"<integer>","season":"<integer>"}'
```

### get_competition_teams

Retrieve all teams participating in a competition. Supports filtering by season. Returns team details including coach and squad. Historical season access may be restricted to recent seasons.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition ID or code (e.g. '2021' or 'PL') |
| `season` | integer | No | Season start year (e.g. 2023). Very old seasons may not be available. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_competition_teams \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>","season":"<integer>"}'
```

### get_match

Retrieve details for a single match by ID, including teams, score, referees, venue, and competition context.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | integer | Yes | Match ID (e.g. 537785) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_match \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match_id":"<integer>"}'
```

### get_match_head2head

Retrieve head-to-head history for the two teams in a match. Returns aggregate stats (total matches, wins, draws, losses per team) and a list of past matches between the two teams.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competitions` | string | No | Comma-separated competition codes to filter by (e.g. 'PL') |
| `limit` | integer | No | Maximum number of past matches to return |
| `match_id` | integer | Yes | Match ID (e.g. 537785) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_match_head2head \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitions":"<string>","limit":"<integer>","match_id":"<integer>"}'
```

### get_person

Retrieve details for a specific person (player or coach) by ID, including current team affiliation, personal information, position, and nationality.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `person_id` | integer | Yes | Person ID (e.g. 44 for Cristiano Ronaldo, 38101 for Erling Haaland) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_person \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"<integer>"}'
```

### get_person_matches

Retrieve matches associated with a specific person. The endpoint may return empty results for some players without competition and date filters due to API tier limitations. For best results, provide both a competition filter and a date range.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competitions` | string | No | Comma-separated competition codes (e.g. 'PL' or 'PL,BL1') |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD) |
| `limit` | integer | No | Maximum number of matches to return |
| `offset` | integer | No | Pagination offset |
| `person_id` | integer | Yes | Person ID (e.g. 44 for Cristiano Ronaldo, 38101 for Erling Haaland) |
| `status` | string | No | Match status: SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, CANCELLED |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_person_matches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitions":"<string>","date_from":"<string>","date_to":"<string>","limit":"<integer>","offset":"<integer>","person_id":"<integer>","status":"<string>"}'
```

### get_team

Retrieve full details for a specific team by ID, including coach, full squad roster with player positions and nationalities, and running competitions.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | integer | Yes | Team ID (e.g. 57 for Arsenal, 5 for Bayern Munich, 64 for Liverpool) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_team \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"team_id":"<integer>"}'
```

### get_team_matches

Retrieve matches for a specific team. Supports filtering by status, venue (HOME/AWAY), season, competitions, date range, and limit. Returns match details with result statistics.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competitions` | string | No | Comma-separated competition codes (e.g. 'PL' or 'PL,CL') |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD) |
| `limit` | integer | No | Maximum number of matches to return |
| `season` | integer | No | Season start year (e.g. 2023) |
| `status` | string | No | Match status: SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, CANCELLED |
| `team_id` | integer | Yes | Team ID (e.g. 57 for Arsenal, 5 for Bayern Munich, 64 for Liverpool) |
| `venue` | string | No | Venue filter: HOME or AWAY |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/get_team_matches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitions":"<string>","date_from":"<string>","date_to":"<string>","limit":"<integer>","season":"<integer>","status":"<string>","team_id":"<integer>","venue":"<string>"}'
```

### list_areas

Retrieve all available geographic areas/regions (countries, continents, sub-regions). Returns a flat list of all areas with their parent hierarchy. Each area carries an id, name, countryCode, optional flag URL, and parent relationship.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/list_areas \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### list_competitions

Retrieve all available competitions/leagues. Optionally filter by geographic area IDs. Returns competition details including current season information.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `areas` | string | No | Comma-separated area IDs to filter by (e.g. '2072' or '2072,2077') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/list_competitions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"areas":"<string>"}'
```

### list_matches

Retrieve matches across multiple competitions. Date range must not exceed 10 days. At least one filter (competitions, ids, date range, or status) should be provided to get meaningful results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competitions` | string | No | Comma-separated competition codes (e.g. 'PL,BL1') |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD) |
| `ids` | string | No | Comma-separated match IDs (e.g. '537785,537786') |
| `status` | string | No | Match status: SCHEDULED, LIVE, IN_PLAY, PAUSED, FINISHED, POSTPONED, CANCELLED |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/list_matches \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"competitions":"<string>","date_from":"<string>","date_to":"<string>","ids":"<string>","status":"<string>"}'
```

### list_teams

Retrieve a paginated list of teams ordered by numeric ID. Use limit and offset for pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of teams to return |
| `offset` | integer | No | Pagination offset |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-football-data-org-api-0ab7d5b8/list_teams \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","offset":"<integer>"}'
```