BeSoccer APIbesoccer.com ↗
Access BeSoccer football data via API: team profiles, squad rosters, match scores, fixtures, league standings, and competition search across global leagues.
What is the BeSoccer API?
The BeSoccer API covers 7 endpoints for football data including team profiles, squad rosters, match details, fixtures, and league standings. Call get_standings to retrieve a full competition table with position, points, goals for/against, and goal difference for any supported league slug. Search for teams or competitions by name, then chain the returned slugs into roster, fixture, and match detail lookups.
curl -X GET 'https://api.parse.bot/scraper/40f3153e-74e9-445f-8cfc-74a616f70503/search_teams?query=barcelona' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace besoccer-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: BeSoccer SDK — league standings, team fixtures, and match detail."""
from parse_apis.besoccer_com_api import BeSoccer, InputNotFound
client = BeSoccer()
# Find a competition by searching, then pull its standings.
comp = client.competitions.search(query="liga", limit=1).first()
if comp is None:
raise SystemExit("No competition found")
print(f"Competition: {comp.name} ({comp.country})")
for standing in client.competitions.standings(competition_id=comp.id, limit=5):
print(f" #{standing.position} {standing.team} — {standing.points}pts")
# Use a team_id from standings to explore fixtures.
top_team = client.competitions.standings(competition_id=comp.id, limit=1).first()
if top_team is not None:
fixture = client.teams.fixtures(team_id=top_team.team_id, limit=1).first()
if fixture is not None:
# Drill into match detail via the typed navigation method.
match = fixture.detail()
print(f"Match: {match.home_team} vs {match.away_team} — {match.score} ({match.status})")
# Team profile and squad from a discovered team_id.
if top_team is not None:
profile = client.teams.profile(team_id=top_team.team_id)
print(f"{profile.name} | Stadium: {profile.stadium} | Coach: {profile.coach}")
for player in client.teams.squad(team_id=top_team.team_id, limit=5):
print(f" {player.name} — {player.position}, age {player.age}")
# Point lookup with error handling for an invalid match.
try:
client.matches.get(match_id="invalid-team/invalid-team/0")
except InputNotFound:
print("Match not found (expected for invalid ID)")
print("exercised: competitions.search / competitions.standings / teams.fixtures / fixture.detail / teams.profile / teams.squad / matches.get")
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.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search query for team name (e.g. 'barcelona', 'manchester'). |
{
"type": "object",
"fields": {
"query": "the search query used",
"teams": "array of team objects with id, name, league, country"
},
"sample": {
"data": {
"query": "barcelona",
"teams": [
{
"id": "ac-monza-sub-16",
"name": "AC Monza U16",
"league": "Serie AB Sub 16",
"country": "IT"
}
]
},
"status": "success"
}
}About the BeSoccer API
What the API Covers
Seven endpoints cover the core data surfaces on BeSoccer: team search, competition search, team profiles, squad rosters, individual match details, team fixture lists, and league standings tables. Every data-retrieval endpoint uses a slug-based identifier — team_id values like real-madrid or athletic-bilbao, and competition_id values like premier_league or primera_division. You can source these slugs from the search_teams and search_competitions endpoints, or read them out of get_standings response fields.
Endpoint Details
get_team_profile returns the team's full name, current head coach, home stadium, and active league. Note that country and founded may come back empty depending on data availability. get_team_squad gives you a complete first-team roster with each player's name, position, age, and nationality code. get_fixtures accepts an optional season parameter (e.g. '2026' targets the 2025–26 season); each fixture object includes match_id, date, home_team, away_team, opponent, venue, and competition. Those match_id values feed directly into get_match.
Match and Standings Data
get_match requires a path-format match_id like ca-boca-juniors/ca-velez-sarsfield/2021234 obtained from get_fixtures. It returns an ISO 8601 date, a score string (X-Y or empty if unstarted), a status from the set {Scheduled, Live, Halftime, Finished, Cancelled, Postponed, Suspended}, and a competition field describing the round. get_standings returns the full league table as an array of objects each containing position, team, team_id, played, won, drawn, lost, goals_for, goals_against, goal_difference, and points, along with the season label from the site.
Search Caveats
search_teams results come from the server-rendered search index. Highly popular clubs may not appear in results because their entries rely on client-side rendering — if a major club is missing, try a less generic query string or source the slug from get_standings for a competition that team participates in.
The BeSoccer API is a managed, monitored endpoint for besoccer.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when besoccer.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official besoccer.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a live league table widget using
get_standingsfor any supported competition slug - Populate a team profile page with stadium, coach, and league data from
get_team_profile - Generate a season fixture calendar for a club using the
get_fixturesseasonparameter - Display full squad rosters with player positions, ages, and nationalities via
get_team_squad - Track match status changes (Scheduled → Live → Finished) using
get_matchwith IDs from fixtures - Build a competition discovery tool that maps league names to slugs via
search_competitions - Cross-reference team slugs from
get_standingsto chain into squad and fixture lookups
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does BeSoccer have an official developer API?+
What does `get_fixtures` return and how do I filter by season?+
match_id, date, home_team, away_team, opponent, venue, and competition. Pass the season parameter to target a specific year: '2026' returns the 2025–26 season, '2027' returns 2026–27. The match_id values in the response are in the format required by get_match.Does the API return player statistics like goals, assists, or minutes played?+
get_team_squad covers player name, position, age, and nationality — per-player performance stats are not included in any current endpoint. You can fork this API on Parse and revise it to add a player statistics endpoint targeting BeSoccer's individual player pages.Why might a well-known team not appear in `search_teams` results?+
get_standings for a competition that team plays in — the team_id slug appears in each standings row and can be passed directly to get_team_profile, get_team_squad, and get_fixtures.Does the API cover historical match data beyond the current season?+
season parameter on get_fixtures and get_standings. However, coverage depth for older seasons depends on what BeSoccer exposes in those views and is not guaranteed to be complete for all competitions or teams. You can fork this API on Parse and revise it to add dedicated historical-season endpoints if broader archive access is needed.