Results by date
A
GET
/v1/results
Settled results over any date range
Settled results over any date range in the archive.
Plan
This endpoint needs Archive.
Calling it on a lower plan returns a 403 naming the plan it needs and
a link to pricing, never a bare refusal.
Parameters
date_from
string
query
Earliest kickoff date, inclusive. ISO
YYYY-MM-DD, evaluated in UTC. e.g. 2024-08-01
date_to
string
query
Latest kickoff date, inclusive. e.g.
2024-08-31
league_id
string
query
Restrict to one competition. Ids come from
/v1/leagues: 39 is the English Premier League, 62 is Ligue 2. e.g. lg_24T9Z0G
country
string
query
Restrict to one country, by name as returned from
/v1/countries. e.g. England
team_id
string
query
Matches involving this club, home or away. e.g.
tm_1E5HXK9
limit
integer
query
Rows per page, 1–1000. Defaults to 100. e.g.
100
page
integer
query
Page number, 1-based. The response carries
total, total_pages, next_page and prev_page, so a UI pager has everything it needs from one call. If you send both page and cursor, page wins. e.g. 2
cursor
string
query
Opaque cursor from
meta.next_cursor. Pages by sort position rather than offset, so page 10,000 is as fast as page 1 and a new match arriving cannot shift the boundary. Pass it back unchanged; do not build or parse one yourself.Returns
data[].match_id
string
Our id for the match. Stable: what you store today still resolves later.
data[].country_name
string
The country the competition belongs to.
data[].league_name
string
The competition's name.
data[].kickoff_utc
integer
Kickoff, as a UTC timestamp.
data[].kickoff_date
string
The kickoff date in UTC, YYYY-MM-DD.
data[].match_status
string
Where the match stands: scheduled, in play by half, half time, finished, postponed, cancelled, abandoned, awarded or walkover.
data[].home_team_name
string
The home side's name.
data[].away_team_name
string
The away side's name.
data[].home_goals
integer
The home side's goals: the final score, after extra time where played.
data[].away_goals
integer
The away side's goals: the final score, after extra time where played.
data[].full_time_result
empty in this example
home, draw or away, on the final score.
data[].home_league_position
integer
The home side's place in the table before the match.
data[].away_league_position
integer
The away side's place in the table before the match.
data[].away_travel_km
integer
How far the away side travelled, in kilometres.
data[].home_kickoff_price
number
The price for a home win at kickoff, as decimal odds.
data[].draw_kickoff_price
number
The price for the draw at kickoff, as decimal odds.
data[].away_kickoff_price
number
The price for an away win at kickoff, as decimal odds.
meta.data_as_of
string
When the data behind this answer was last brought up to date.
meta.request_id
string
This request's id, to quote to support.
meta.count
integer
How many items are in this answer.
meta.next_cursor
string
Pass it as cursor for the next page; empty on the last.
meta.page
integer
This page's number.
meta.per_page
integer
How many items a page holds.
meta.total
integer
How many items match in all.
meta.total_pages
integer
Total pages.
meta.next_page
integer
Next page.
meta.prev_page
empty in this example
Prev page.
Request
curl "https://api.footballsoccerapi.com/v1/results?date_from=2024-08-01&date_to=2024-08-31&league_id=lg_24T9Z0G" \ -H "X-API-Key: $FSAPI_KEY"
const res = await fetch("https://api.footballsoccerapi.com/v1/results?date_from=2024-08-01&date_to=2024-08-31&league_id=lg_24T9Z0G", { headers: { "X-API-Key": process.env.FSAPI_KEY } }); const { data, meta } = await res.json();
import os, requests r = requests.get( "https://api.footballsoccerapi.com/v1/results?date_from=2024-08-01&date_to=2024-08-31&league_id=lg_24T9Z0G", headers={"X-API-Key": os.environ["FSAPI_KEY"]}, ) data = r.json()["data"]
$ch = curl_init("https://api.footballsoccerapi.com/v1/results?date_from=2024-08-01&date_to=2024-08-31&league_id=lg_24T9Z0G"); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["X-API-Key: {$key}"], ]); $data = json_decode(curl_exec($ch), true)["data"];
Example response
A real row from the archive, fetched when this page rendered. Run it against your own key below.
200 OK
application/json
{
"data": [
{
"match_id": "mt_28QVFGW",
"country_name": "Colombia",
"league_name": "Primera A",
"kickoff_utc": 1793228400,
"kickoff_date": "2026-10-28",
"match_status": "finished",
"home_team_name": "Once Caldas",
"away_team_name": "Alianza Valledupar",
"home_goals": 1,
"away_goals": 0,
"full_time_result": null,
"home_league_position": 7,
"away_league_position": 16,
"away_travel_km": 650,
"home_kickoff_price": 1.58,
"draw_kickoff_price": 3.7,
"away_kickoff_price": 6.25
},
{
"match_id": "mt_1SGZZ85",
"country_name": "Germany",
"league_name": "DFB Pokal",
"kickoff_utc": 1793216700,
"kickoff_date": "2026-10-28",
"match_status": "finished",
"home_team_name": "Hannover 96",
"away_team_name": "1. FC Kaiserslautern",
"home_goals": 0,
"away_goals": 2,
"full_time_result": "away",
"home_league_position": null,
"away_league_position": null,
"away_travel_km": 354,
"home_kickoff_price": 1.66,
"draw_kickoff_price": 4.2,
"away_kickoff_price": 4.4
}
],
"meta": {
"data_as_of": "2026-10-29T04:32:57Z",
"request_id": "01J9QW3C7M4KX2VB",
"count": 2,
"next_cursor": "MTcyOTMzNzQwMDoxMjA4MDk5",
"page": 1,
"per_page": 100,
"total": 380,
"total_pages": 4,
"next_page": 2,
"prev_page": null
}
}
Run it live
Paste your key and fire the real request. The key is kept in this browser only and never sent anywhere but the API.