Introduction

Pep Guardiola does not just line players up and tell them to play. He builds a system. Every player has a role. Every role connects to another. The striker presses because the winger tracks back. The fullback overlaps because the midfielder tucks in. It only works because everyone understands the structure.

A football API works the same way. Before you make your first call, before you pull a live score or a player’s stats or a league table, there is a structure underneath all of it. Seven objects. Each one with a unique ID. Each one connecting to the others in a specific way. Learn that structure, and the entire API starts to feel like second nature. Skip it, and you will spend hours wondering why your data is not matching up the way you expected.

This blog walks you through the seven data objects inside Entity Sport’s football API — what each one is, what ID it carries, what it connects to, and how they chain together when you are making real API calls. We also cover the core data APIs — Seasons, Competitions, Matches, Teams, and Players — and what each one returns in practice.

Here’s a guide to Football API.

Why Does a Football API Data Use Objects?

When you call a football API, you are not just getting a blob of data back. You are getting structured records — objects — where each one represents a real-world entity: a season, a competition, a match, a team, a player.

The reason this matters is relationships. A match does not exist in isolation. It belongs to a round, which belongs to a competition, which belongs to a season. The teams and players in that match each have their own records. The API uses unique IDs on every object so that these relationships are explicit. When a match response returns a cid of 1452, you know exactly which competition that match belongs to, and you can use that cid to pull the full competition record, standings, and round structure.

This is what separates a well-structured sports API from one that just dumps data at you. The object model is the grammar of the API. Once you understand it, every response you get starts to make sense immediately.

The 7 API Objects in Entity Sport’s Football API Data

Entity Sport’s football API has seven objects in total. Each one has a unique identifier — built from the first letter of the object name followed by id. Here they all are.

Object	Unique ID	What It Holds
Season	sid	Year timeframe. 2016, 2025-26, etc. The calendar wrapper for all competitions.
Competition	cid	A tournament, league, or cup. Holds matches, teams, standings, player stats, and season context.
Round	rid	A sub-competition inside a competition. Group stages, knockout rounds, or series within a tour.
Match	mid	The core object. Connects competition, round, teams, and players into one record.
Inning	iid	A single match period. One match can have multiple innings (e.g. two halves).
Team	tid	A sports team. Name, logo, country, team type.
Player	pid	A sports player. Profile, position, career stats, in-match data.

A single API response can contain one object, many objects, or no objects at all, depending on what endpoint you called and what filters you applied. The structure is always consistent — which means once you learn it once, it works the same way across every endpoint.

Each Object, Explained

1. Season (sid)

A Season is a year timeframe. It is the outermost layer of the entire data structure — the calendar that everything else sits inside.

How seasons are named: If a competition runs between March and September, it takes the current year as its season name — 2025, 2026. If it runs from October through February, it crosses two calendar years and gets a cross-year name: 2025-26, 2024-25. Four digits for the current year, two for the next, separated by a hyphen.

Why this matters for your integration: when you are querying historical data — last season’s player stats, a previous season’s standings, a team’s results over two years — the sid is how you scope the request. The season is the filter that tells the API which timeframe you are working in.

ID	sid — e.g. sid=2025 or sid=2025-26

Connects to: Competitions (every competition has a season it belongs to).

2. Competition (cid)

A Competition is a tournament, a league, or a cup. The Premier League is a competition. The UEFA Champions League is a competition. The FIFA World Cup is a competition. The FA Cup is a competition.

A competition object contains everything that makes up that tournament’s identity — the matches played within it, the teams competing, player performance data aggregated at competition level, the standings or points table, the season it belongs to, dates, type, and category.

The cid is one of the most-used IDs in the entire API. Most of your calls will pass a cid to scope the data you want — give me all matches in this competition, give me the standings for this league, give me player stats in this tournament.

ID	cid — e.g. cid=1 (Premier League), cid=89 (Champions League)

Connects to: Season (sid), Rounds (rid), Matches (mid), Teams (tid), Players (pid).

Entity Sport’s football API data covers 300+ competitions across 100+ countries. The coverage level of a competition — Level 1 through Level 4 — determines how much data is available within that competition object. Level 1 gives you everything: full player stats, formations, commentary, lineups. Level 4 gives you live tables and real-time scores only.

3. Round (rid)

A Round is a sub-competition that lives inside a competition. When a tournament has structure within it — group stages, knockout rounds, quarter-finals, semi-finals, or a tour that contains different match formats — those sub-structures are modelled as rounds.

The FIFA World Cup is a clear example. It has a Group Stage round and a Knockout Stage round. The UEFA Champions League has a Group Stage, Last 16, Quarter-Finals, Semi-Finals, and Final — each one is a round. A domestic league that has a regular season and a playoff phase has two rounds.

ID	rid — scoped inside a cid, so always used together with a competition ID

Connects to: Competition (cid), Matches (mid). A round belongs to a competition and contains matches.

For most live score apps and results pages, you will not need to think about rounds much — you will query by competition and date. But if you are building a tournament bracket view or a group stage display for a cup competition, the round structure is what makes it work.

4. Match (mid)

The Match is the core of the entire API. Everything else exists to give context to a match or to give detail about what happened inside one.

A match object connects: the competition it belongs to (cid), the round it sits in (rid), the two teams playing (tid), the players involved (pid), and the innings or periods of play (iid). It is the object that ties every other object together into one record.

The mid — match ID — is the key you will use most often once you are live. When you pull the schedule and get a list of today’s matches, each one comes with a mid. That mid is what you pass to the Live Score API to stream events, to the Roster API to get the lineup, to the Fantasy Football API data to pull live player points. Everything downstream of a live match flows from its mid.

ID	mid — every match has a unique match ID across the entire data feed

Connects to: Competition (cid), Round (rid), Teams (tid), Players (pid), Innings (iid). The match is the hub.

5. Inning (iid)

An Inning holds single match period data. In football, this maps to a match half — first half, second half, and where applicable, extra time. Each period is a separate inning object with its own iid.

For most football use cases — live scores, match events, fantasy points — you will not interact with innings directly. The higher-level match and event APIs abstract this for you. But if you are building detailed match analytics, period-by-period stat breakdowns, or a half-time vs full-time performance comparison tool, the inning object is where that data lives.

ID	iid — scoped inside a mid, always tied to a specific match

Connects to: Match (mid). An inning only exists within a match.

6. Team (tid)

A Team is a sports team. Name, logo, country, and type of team — club, national, youth — are the core fields. The tid connects the team to every competition it participates in, every match it plays, and every player in its squad.

In practice, you will encounter tids constantly. Every match response returns two tids — the home team and the away team. Every competition has a list of tids — the teams competing. The Team API uses the tid as its primary filter to return a team’s profile, match history, roster, and season statistics.

ID	tid — consistent across all competitions and seasons for the same club

Connects to: Competition (cid), Match (mid), Player (pid). A team appears in competitions, plays matches, and has players.

7. Player (pid)

A Player is a sports player. The pid is the unique identifier that follows a player across their entire career in the data feed — across seasons, across competitions, across club transfers. Mohamed Salah’s pid is the same whether you are pulling his Premier League stats from last season or his Champions League data from three years ago.

The player object carries profile data — name, position, nationality, club — and connects to career statistics, in-match performance data, and fantasy points. For fantasy platforms and player analytics tools, the pid is the ID you will be working with constantly.

ID	pid — unique per player, consistent across all seasons and competitions

Connects to: Team (tid), Match (mid), Competition (cid). A player belongs to a team, appears in matches, and accumulates stats within competitions.

Here’s a guide to building your own football Fantasy platform using a Football API.

How the Objects Connect to Each Other

The seven objects are not independent. They form a hierarchy — and once you see that hierarchy, the entire API starts to feel obvious.

Here is the chain, top to bottom:

And here is what that means in practice — once you have one ID, here is what you can reach:

If you have…	You can get…
sid (Season)	All competitions in that season
cid (Competition)	All rounds, matches, teams, and player stats in that tournament
rid (Round)	All matches in that group stage or knockout round
mid (Match)	Teams, players, innings, and events for that specific match
tid (Team)	Roster, match history, season stats, players
pid (Player)	Profile, career stats, in-match performance data

This is the key insight that makes the API click. You are not memorising endpoints in isolation. You are learning a connected graph. Every ID you have is a door to more data.

btn_link=”https://www.entitysport.com/football-api-coverage/”

The Core Data APIs and What They Return

With the seven objects understood, the individual data APIs map cleanly onto them. Here is how each one works.

Seasons API

The Seasons API returns a list of all available seasons in the data feed. This is the entry point when you are working with historical data — you call Seasons to get a list of valid sids, then use those sids to scope requests for competitions, matches, or player stats within a specific timeframe.

What it returns: Season name, season ID (sid), start and end dates, and whether the season is current or historical.

When you use it: Historical stat comparisons, season-over-season analysis, scoping any request to a specific year or cross-year period.

Primary object

Season → sid

Most platforms do not need to call the Seasons API on every request — you typically call it once, cache the season list, and use the sids you care about as parameters in other calls. The current season sid is the one you will pass most often.

Competitions API

The Competitions API returns all competitions available in the data feed — or all competitions within a specific season if you filter by sid. Every competition you have access to under your plan comes back as a competition object with its cid, name, country, category, dates, and season context.

What it returns: Competition ID (cid), name, category (domestic league, cup, international), country, current season, start and end dates, and coverage level.

When you use it: Building a competition selector UI, populating a league dropdown, filtering matches by competition, understanding which leagues your plan gives you access to.

Primary object

Competition → cid

A practical move: call Competitions once on app load, store the cid for each league your users care about, and use those cids as the filter in every subsequent call. You do not need to re-fetch the competition list on every request — it changes slowly. Refresh it daily or on app startup.

Matches API

The Matches API is the most-called endpoint in most football platforms. It returns match records — upcoming, live, and completed — scoped by competition, team, date range, or status. Every match comes with its mid, which is the key that unlocks every other match-level data point in the feed.

What it returns: Match ID (mid), status (upcoming/live/completed), competition (cid), round (rid), home team (tid), away team (tid), score, start time, venue, and — for live matches — current minute and match events.

When you use it: Fixture lists, results pages, today’s matches, match calendar views, and as the source of mid values for all live-match API calls.

Primary object

Match → mid

The match status field is the one to build your polling logic around. Upcoming matches need to be fetched periodically to catch any schedule changes. Live matches are where you switch to WebSocket (if you are on Gold+) or increase your polling frequency. Completed matches are static — fetch once and cache.

Every platform starts with the Matches API. The mid you get here is the input to your live score stream, your lineup fetch, your fantasy points update, and your post-match stats pull.

Teams API

The Teams API returns team records — scoped by competition, by season, or by a specific tid. It is the team-level view of the data feed.

What it returns: Team ID (tid), name, logo, country, type, current squad, match history, and season statistics. At competition level, it returns all teams competing in a given cid.

When you use it: Club profile pages, team form trackers, head-to-head pre-match views, competition team lists, squad displays.

Primary object

Team → tid

The Teams API and the Roster API overlap in territory but serve different purposes. The Roster API is match-time — who is in the confirmed lineup for tonight’s game. The Teams API is identity and history — who this club is, what their record looks like, who is in their full squad across the season. For a club profile page, you use Teams. For a pre-match lineup card, you use Roster.

Players API

The Players API returns player records — scoped by team (tid), by competition (cid), or by a specific player ID (pid). It is the most granular endpoint in the feed, and the one that powers fantasy platforms, player comparison tools, and analytics dashboards.

What it returns: Player ID (pid), name, position, nationality, current club (tid), career statistics, and in-match performance data — shots, passes, tackles, dribbles, interceptions, saves, player rating, and disciplinary record.

When you use it: Player profile pages, fantasy team pickers, form indicators, stat-heavy editorial content, player comparison tools, and valuation models for real-money gaming.

Primary object

Player → pid

The depth of data the Players API returns depends on the coverage level of the competition. Level 1 competitions — Premier League, La Liga, Champions League, FIFA World Cup — give you the full 50+ data type breakdown: attacking stats, passing accuracy, defensive actions, goalkeeping metrics. Lower coverage tiers return core event data only. If player analytics is your product, confirm your target leagues are at Level 1 before you build.

A Real Example: What a Call Chain Looks Like

Here is how the object model plays out in a real integration. Say you are building a Champions League tracker.

• Call Competitions with sid=2025-26 — get back the Champions League cid (let’s say cid=89)
• Call Matches with cid=89 — get back all matches in the tournament, each with a mid
• For tonight’s match (mid=44210) — call Roster to get the confirmed lineups, each player returned with their pid
• Open a Live Score stream for mid=44210 — events come in with the tid of the scoring team and the pid of the scorer
• For each pid in the event — update the player’s tally in your Fantasy Football points tracker
• After the match — call Players with the pids from tonight’s lineups to store updated career stats
• Call Competitions again with cid=89 — get updated standings after the result

Seven calls. Seven objects. One connected chain. That is the API object model working exactly as designed.

Frequently Asked Questions

What is the difference between a Round and a Competition in the Entity Sport football API data?

A Competition (cid) is the top-level tournament — the Premier League, the Champions League, the FA Cup. A Round (rid) is a sub-division within that competition — the Group Stage, the Round of 16, the Final. Every round belongs to one competition. Not every competition has rounds; domestic leagues that run as a single continuous stage often do not use the round structure at all.

Do object IDs stay the same across seasons?

Yes. The tid for Manchester City is the same tid whether you are pulling their 2023-24 data or their 2025-26 data. The pid for Erling Haaland does not change when he moves clubs or plays in a different competition. The cid for the Premier League is consistent year over year. Only the sid changes each season. This is what makes cross-season comparisons possible — the IDs are stable anchors.

What is the sid format for a competition that runs across two calendar years?

Four digits for the starting year, two digits for the ending year, separated by a hyphen. A competition running from August 2025 to May 2026 uses sid 2025-26. A competition running entirely within a single calendar year — like most international tournaments — uses just the four-digit year: 2026.

How do I get the mid for a specific match?

Call the Matches API filtered by cid (competition) and date or status. Every match in the response carries a mid. That mid is what you pass to the Live Score API, the Roster API, and the Fantasy Football API data for any match-level data. The Schedule API on the product side is the same call — it uses the Matches endpoint underneath.

Can I query the Players API without knowing the pid first?

Yes. You can call the Players API scoped by a tid (give me all players in this team’s squad) or by a cid (give me all players who appeared in this competition). The response returns each player with their pid, which you can then use for individual player detail calls. The pid is the result of that first query, not a prerequisite for it.

Get Started

The object model is the foundation. Everything else in Entity Sport’s football API data builds on top of it. Seven objects, seven IDs, one connected structure that scales from a single match to 100+ competitions across 100+ countries.

Read the Football API documentation. The free development API gives you sandbox access — two competitions, no credit card — to test the object model end to end before committing to a plan.

Also read:

Football API for SaaS: How Modern Sports Platforms Scale with Real-Time Football Data

How to Choose the Right Football API Provider – Complete Guide