Match Endpoints

V2 Football API: 37 match sub-endpoints covering scores, analytics, odds, lineups, shotmaps, AI insights, and more

Base URL

https://v2.football.sportsapipro.com

All match endpoints use the pattern /api/match/{matchId}/...

Finding Match IDs: Use /api/live for current matches, /api/schedule/{date} for scheduled matches, or /api/search?q=team to find matches by team name. Match IDs are numeric (e.g., 14025056).

---

Core Match Data

Get Match Details

GET /api/match/{matchId}

Returns full match details including scores, teams, venue, status, timestamps, and entity IDs for players, referees, and venues.

matchId · number · required

Numeric match ID. Discover via /api/live, /api/schedule/{date}, or /api/search.

Get Lineups

GET /api/match/{matchId}/lineups

Returns confirmed starting lineups for both teams, including formation, player positions, jersey numbers, and substitutes.

Availability: Only available once lineups are confirmed — typically 30–60 minutes before kick-off. Returns empty for matches further in the future.

Get Statistics

GET /api/match/{matchId}/statistics

Returns match statistics: possession, shots (on/off target), passes, fouls, corners, offsides, and more. Broken down by period (1st half, 2nd half, total).

Availability: Available during live matches and after full-time. Not available for pre-match.

Get Incidents

GET /api/match/{matchId}/incidents

Returns all match events in chronological order: goals, cards (yellow/red), substitutions, VAR decisions, penalty shootout events.

Get Scores

GET /api/match/{matchId}/scores

Returns detailed score breakdown including period scores (1st half, 2nd half), extra time, penalty shootout results, and aggregate scores for two-legged ties.

Get Referee

GET /api/match/{matchId}/referee

Returns referee details assigned to the match. Use the returned referee.id to call referee-specific endpoints.

Get Venue

GET /api/match/{matchId}/venue

Returns venue information: name, city, country, capacity, and coordinates. Use the returned venue.id for venue-specific endpoints.

---

Match Status Codes

Every match object includes a status.code field (numeric) and a status.description (text). Use the numeric code for programmatic logic.

Code	Description	Meaning
0	Not started	Match has not kicked off yet
6	1st half	First half in progress
7	2nd half	Second half in progress
31	Halftime	Halftime break
40	Extra time — 1st half	First half of extra time
41	Extra time — 2nd half	Second half of extra time
50	Penalty shootout	Penalty shootout in progress
60	Postponed	Match postponed to a later date
70	Canceled	Match canceled and will not be played
80	Interrupted	Match interrupted (may resume)
90	Abandoned	Match abandoned and will not resume
100	Ended	Match ended in regulation (90 min + stoppage)
110	Ended after extra time	Match ended after 120 minutes
120	Ended after penalties	Match ended after penalty shootout

Detecting regulation vs. overtime (Ronen’s question):

• Regulation ended: status.code === 100 — the match finished in normal time (90 min + stoppage).
• Extra time started: status.code === 40 or 41 — the match is now in overtime.
• Extra time ended: status.code === 110 — final result was decided in extra time.
• Penalties: status.code === 50 (in progress) or 120 (ended after penalties).

To detect the transition from regulation to overtime, poll the match and watch for status.code changing from 7 (2nd half) → 31 (halftime, brief break) → 40 (extra time 1st half). If it jumps from 7 → 100, regulation ended normally with no extra time.

---

Advanced Analytics

Shotmap

GET /api/match/{matchId}/shotmap

Returns shot map data with xG (expected goals) values for each shot, including coordinates, player, shot type (foot/header), and outcome (goal/saved/blocked/off-target).

Availability: Available during live matches (updates in real-time) and after full-time. Not available pre-match.

Momentum Graph

GET /api/match/{matchId}/graph

Returns match momentum/pressure graph data over time. Each data point represents the attacking pressure at a given minute.

Average Positions

GET /api/match/{matchId}/average-positions

Returns average player positions on the pitch for both teams. Useful for tactical analysis and formation visualization.

Availability: Available during live matches and after full-time only.

AI Insights

GET /api/match/{matchId}/ai-insights?lang={lang}

Returns AI-generated post-match analysis with key talking points, tactical observations, and performance summaries.

lang · string · default: "en"

Language code for the analysis (e.g., en, es, de, fr, pt).

Availability: Post-match only (this is the ai-insights-postmatch variant internally). The pre-match/live ai-insights endpoint returns 403 Forbidden and is not usable. Not available for all matches — primarily top-tier competitions. Returns 404 for matches without AI analysis.

Team Heatmap

GET /api/match/{matchId}/heatmap/{teamId}

Returns team heatmap data for the match, showing areas of the pitch where the team was most active.

teamId · number · required

Numeric team ID. Get from the match details response (homeTeam.id or awayTeam.id).

---

Player-Specific

Best Players / MOTM

GET /api/match/{matchId}/best-players

Returns the best-performing players from the match with ratings and key statistics.

Award Details

GET /api/match/{matchId}/award

Returns official man-of-the-match award details.

All Player Statistics

GET /api/match/{matchId}/player-statistics

Returns comprehensive statistics for all players in the match: passes, tackles, shots, dribbles, duels, and ratings.

Specific Player Statistics

GET /api/match/{matchId}/player/{playerId}/statistics

Returns detailed statistics for a specific player in the match.

playerId · number · required

Numeric player ID. Get from lineups or match details.

---

Betting & Odds

Featured Odds

GET /api/match/{matchId}/odds?scope={scope}&provider={provider}

Returns odds for the match from a specific provider.

scope · string · default: "featured"

featured for main markets or all for all available markets.

provider · number · default: "1"

Odds provider ID. Use /api/odds/providers/{countryCode} to list available providers.

All Odds

GET /api/match/{matchId}/odds/all

Returns odds from all available providers and markets.

Pre-Match Odds

GET /api/match/{matchId}/odds/pre-match

Returns pre-match odds snapshot. Available before kick-off.

Availability: Pre-match only. Returns 404 after the match has ended.

Live Odds

GET /api/match/{matchId}/odds/live

Returns live in-play odds that update during the match.

Availability: Live matches only. Returns 404 for pre-match or finished matches.

Winning Odds

GET /api/match/{matchId}/winning-odds

Returns the winning odds movement for the match.

Team Streaks

GET /api/match/{matchId}/streaks

Returns recent streak data for both teams (e.g., “5 wins in a row”, “unbeaten in 10”).

Streaks with Odds

GET /api/match/{matchId}/streaks/odds

Returns streak data combined with relevant odds markets.

---

Pre-Match Data

The following endpoints are pre-match only. They return 404 for live or finished matches.

Head to Head

GET /api/match/{matchId}/h2h

Returns head-to-head history between the two teams: previous meetings, results, and statistics.

Pre-Game Form

GET /api/match/{matchId}/pregame-form

Returns recent form for both teams going into the match (last 5–10 results).

Predicted Lineups

GET /api/match/{matchId}/predicted-lineups

Returns AI-predicted lineups before the official lineups are announced.

Predicted lineups are replaced by confirmed lineups once available (typically 30–60 min before kick-off).

---

Media & Social

Highlights

GET /api/match/{matchId}/highlights

Returns video highlight links for the match (when available).

Media

GET /api/match/{matchId}/media

Returns media content associated with the match (photos, videos).

Media Summary

GET /api/match/{matchId}/media-summary?country={country}

Returns a localized media summary of the match.

country · string · default: "GB"

Country code for localized content (e.g., GB, US, DE). Defaults to GB.

Tweets

GET /api/match/{matchId}/tweets

Returns tweets related to the match from official team and league accounts.

Comments

GET /api/match/{matchId}/comments

Returns user comments/discussions about the match.

Fan Votes

GET /api/match/{matchId}/votes

Returns fan voting results (e.g., player of the match polls).

---

Other

Managers

GET /api/match/{matchId}/managers

Returns manager/head coach details for both teams. Use the returned manager.id for manager-specific endpoints.

Penalties

GET /api/match/{matchId}/penalties

Returns penalty shootout details: order, takers, outcomes, and scores after each kick.

Only available for matches that went to a penalty shootout.

TV Channels

GET /api/match/{matchId}/channels

Returns TV broadcast channels organized by country, including channel names and broadcast times.

Jerseys

GET /api/match/{matchId}/jerseys

Returns home and away jersey details for both teams: colors, patterns, and goalkeeper kit.

Fantasy

GET /api/match/{matchId}/fantasy

Returns fantasy-relevant data for the match: points, bonuses, and player ownership.

---

Example Requests

cURL

curl -X GET "https://v2.football.sportsapipro.com/api/match/14025056/statistics" \
  -H "x-api-key: YOUR_API_KEY"