Build match summary, stats and line-up tabs
Use the exact id and league parameters for single-match detail, join player IDs and display confirmed formations and optional ratings.
Endpoint reference:matchStep 1: Identify
Prepare id, league from matching records.
Step 2: Request
GET /api/v1/football/match
Step 3: Validate
Check resource IDs, actual dates and available fields.
Step 4: Reuse
Save a shared snapshot; this feed's source cache lasts 30 seconds.
What you will build
Retrieve one match detail record to power the match-centre sidebar. This endpoint uses id and league, unlike the fixture endpoint's leagueId and matchId names.
Supply a match static_id as id and the commentary league ID as league. Includes the same optional MatchDetail sections as competition statistics, including player_stats @rating, not just lineups. Cache 30 seconds; a blank rating is unavailable, not zero. Not included in Starter's league-scoped service set.
Check your plan before starting
This endpoint requires Growth or Pro; it is not part of Starter or the Starter trial. A valid Starter key will not unlock it. Use an eligible account with the endpoint enabled, and check the reference for any specialist connection requirements.
The service being published does not guarantee every optional field for every competition or fixture. Check the actual records relevant to the page you are building.
Find identifiers and prepare the request
Take the durable static match ID and its matching competition ID from fixtures. Send them as id and league respectively.
Identifiers are strings belonging to specific resources. Keep competition, stage, team, player and static match IDs in separate fields. The code reads identifiers from your environment rather than assuming one sample league is valid for everyone. Growth and Pro customers can discover IDs in the directory; Starter customers should use their saved league IDs from Dashboard → Settings and their permitted fixture or squad records.
- id: required; positive numeric identifier sent as a string.
- league: required; positive numeric identifier sent as a string.
Make an authenticated server-side request
Set FOOTBALLAPI_KEY to your customer REST key in your server's secret manager. Also set FOOTBALL_MATCH_ID for id; FOOTBALL_LEAGUE_ID for league using the formats above. Save the code as request.mjs and run node request.mjs with Node.js 20 or newer. A widget installation key cannot replace the REST key.
The example makes one request and does not retry automatically. Its 60-second client timeout leaves room for the API's bounded source-read recovery; it is not a promised response time or a browser loading recommendation. Test once in the signed-in playground, then run from a server you control. Visitors should request your own cached delivery route.
A successful transport response is the beginning of validation, not proof that every optional record is populated. Preserve the response metadata alongside the data.
// Save as request.mjs and run: node request.mjs (Node.js 20+).
// Set the environment variables listed above first. Run only on your server.
const requiredEnv = name => {
const value = process.env[name]?.trim();
if (!value) throw new Error(`Set ${name} before running this example`);
return value;
};
const key = requiredEnv("FOOTBALLAPI_KEY");
const url = new URL("https://footballapi.net/api/v1/football/match");
url.searchParams.set("id", requiredEnv("FOOTBALL_MATCH_ID"));
url.searchParams.set("league", requiredEnv("FOOTBALL_LEAGUE_ID"));
const response = await fetch(url, {
headers: { Authorization: `Bearer ${key}`, Accept: "application/json" },
signal: AbortSignal.timeout(60000)
});
if (!response.ok) {
const retryAfter = response.headers.get("retry-after");
throw new Error(`Football API HTTP ${response.status}; Retry-After: ${retryAfter ?? "not supplied"}`);
}
const { data, meta } = await response.json();
console.log({ data, meta });Interpret and render the response
Verify static_id and actual match date. Inspect teams, substitutes, substitutions, stats and player_stats separately; an empty section must not erase a populated section from a newer saved response.
Place the home team on the left and away team on the right. Use supplied formation_pos and position fields for the pitch and player_stats rating only as the optional rating for this match.
Responses use a data object and meta information. Feed-native fields may use @ prefixes, and repeated elements can be an object or an array. The helper below is an adapter utility, not a standalone renderer: apply it to the specific collection shown in the reference. Preserve missing values instead of turning unavailable statistics into zero.
const asArray = value => value == null ? [] : Array.isArray(value) ? value : [value];
// Adapter helper: apply to the known collection from this endpoint's reference.
// It does not guess a response path or render a complete page.
// Keep static match IDs and player/team IDs in your saved normalised records.Save requests without losing useful updates
Fetch one detail model in the background and reuse it for all tabs. A tab click should read saved data rather than independently fetching summary, stats and lineups.
The published server cache interval for this endpoint is 30 seconds. This is a server reuse interval, not a guarantee of new data every 30 seconds and not a promise that requests served from the API cache are free. Your own cache prevents repeat customer API requests.
Include the endpoint, sorted query parameters, account access scope and relevant date or season in your cache key. Coalesce concurrent misses, serve your own saved response while one background refresh runs, and record its fetched time. Apply corrections to stored results without discarding stable IDs.
Date and time fields are retained as supplied. Establish the timezone for the particular feed before converting a kickoff to UTC or a visitor's local time; do not append Z to a timezone-less value just to make it parse.
Check the result before going live
For substitutions, join explicit on_id and off_id; do not infer which player entered from list ordering. Reconcile duplicated goals and cards using identity, team, type and minute.
A 400 response usually needs an input correction, 401 needs a valid key, and 403 needs a plan, saved-league or access check. A disabled endpoint can return 503. Honour Retry-After on 429 responses rather than retrying immediately. Back off on temporary 5xx errors. An empty successful collection is not a reason to launch an unbounded retry loop.
- Use a known relevant fixture or player for your first comparison.
- Check that returned competition, season and dates match the page you are building.
- Keep keys and raw authentication headers out of error logs and support screenshots.
Related tutorials
Build a football product / 10 min
Build formations, ratings and heatmap views
Use confirmed team positions, match-specific ratings and verified heatmap coordinates without confusing predictions, season averages or tracking coverage.
Build a football product / 11 min
Build a fast football match centre
Combine fixtures, live states, summary events, statistics, formations, images and odds into one preloaded football match-centre model.
Getting started / 9 min
Make your first FootballAPI.net request
Create an account, activate the right football plan, keep your API key server-side and make a first authenticated scores request with cURL or PHP.
Performance and operations / 12 min
Save requests with shared football API caches
Design server-side caching, request coalescing, prewarming and usage budgets so football pages load quickly without unnecessary API calls.