# Besoccer — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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.

> Access comprehensive football data to discover team profiles, player rosters, match results, upcoming fixtures, and league standings across competitions. Search for specific teams and competitions to build your own soccer analytics, fantasy league tools, or sports tracking applications.

**Category:** Sports | **Website:** [www.besoccer.com/](https://www.besoccer.com/) | **Docs:** [parse.bot/marketplace/54c37464-222a-4d57-81af-ac1b6476a0b2/besoccer-com-api](https://parse.bot/marketplace/54c37464-222a-4d57-81af-ac1b6476a0b2/besoccer-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get fixtures

Get fixtures (upcoming and recent matches) for a team. Returns all matches for the current or specified season with dates, opponents, competition info, and match IDs usable with get_match.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `season` | string | No | Season year filter (e.g. '2026' for the 2025-26 season, '2027' for 2026-27). When omitted, returns the current season. |
| `team_id` | string | Yes | Team slug identifier (e.g. 'barcelona', 'real-madrid'). Obtainable from search_teams or get_standings. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/get-fixtures \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"season":"<string>","team_id":"<string>"}'
```

### Get match

Get details for a specific match including teams, score, date, status, and competition. The match_id is a path in format 'home-slug/away-slug/numeric-id', obtainable from get_fixtures results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `match_id` | string | Yes | Match path identifier in format 'home-slug/away-slug/numeric-id' (e.g. 'ca-boca-juniors/ca-velez-sarsfield/2026239823'). Obtainable from get_fixtures results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/get-match \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"match_id":"<string>"}'
```

### Get standings

Get league standings/table for a competition. Returns the full table with position, team name, matches played, wins, draws, losses, goals for/against, goal difference, and points.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `competition_id` | string | Yes | Competition slug identifier (e.g. 'primera_division', 'premier_league', 'serie_a_brazil'). Obtainable from search_competitions or competition links on the site. |
| `season` | string | No | Season year filter (e.g. '2026' for 2025-26 season). When omitted, returns the current season standings. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/get-standings \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"competition_id":"<string>","season":"<string>"}'
```

### Get team profile

Get detailed profile information for a team including name, league, stadium, and coach. The team_id is a URL slug obtainable from search_teams results or standings.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | string | Yes | Team slug identifier (e.g. 'barcelona', 'real-madrid', 'athletic-bilbao'). Obtainable from search_teams, get_standings, or get_fixtures results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/get-team-profile \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"team_id":"<string>"}'
```

### Get team squad

Get the current squad/roster for a team. Returns all first-team players with their position, age, and nationality code.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `team_id` | string | Yes | Team slug identifier (e.g. 'barcelona', 'real-madrid'). Obtainable from search_teams or get_standings. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/get-team-squad \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"team_id":"<string>"}'
```

### Search competitions

Search for football competitions/leagues by name. Returns competitions from BeSoccer's search index with their slug ID, name, and country.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query for competition name (e.g. 'liga', 'premier', 'champions'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/search-competitions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Search teams

Search for football teams by name. Returns teams from BeSoccer's search index with their slug ID, name, league, and country. Results come from the server-rendered search page and may not include the most obvious/popular matches which require client-side rendering.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query for team name (e.g. 'barcelona', 'manchester'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/besoccer/search-teams \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.