Season Results

Get all match results for a specific competition and season with standard pagination

GET /games/season-results

Season Results

cURL

curl --request GET \
  --url https://v1.football.sportsapipro.com/games/season-results \
  --header 'x-api-key: <api-key>'

200

{
  "seasonNum": 123,
  "seasonName": "<string>",
  "competition": {
    "id": 123,
    "name": "<string>",
    "countryId": 123
  },
  "pagination": {
    "page": 123,
    "pageSize": 123,
    "totalGames": 123,
    "totalPages": 123,
    "hasMore": true
  },
  "games": [
    {
      "id": 123,
      "competitionId": 123,
      "seasonNum": 123,
      "startTime": "<string>",
      "statusGroup": 123,
      "homeCompetitor": {
        "id": 123,
        "name": "<string>",
        "score": 123
      },
      "awayCompetitor": {
        "id": 123,
        "name": "<string>",
        "score": 123
      },
      "winner": 123
    }
  ],
  "competitors": "<array>",
  "countries": "<array>"
}

Season Results

Retrieve all completed match results for a specific competition season with standard page-based pagination.

Current Season Only

Due to upstream data provider limitations, this endpoint only supports the current season. Historical season data (past seasons) is not accessible through the match results API.

• Current season requests → Returns paginated match results ✅
• Historical season requests → Returns 422 error with explanation ❌

For historical data, the /standings endpoint provides final standings for previous seasons.

Endpoint

GET /games/season-results

Parameters

Parameter	Type	Required	Description
competitions	number	Yes	Competition ID (e.g., 7 for Premier League)
seasonNum	number	Yes	Season number from /standings?withSeasonsFilter=true
page	number	No	Page number (default: 1)
pageSize	number	No	Results per page (default: 50, max: 100)
showOdds	boolean	No	Include betting odds (default: false)

Discovering Season Numbers

Before using this endpoint, discover available seasons using the standings endpoint:

curl -X GET "https://v1.football.sportsapipro.com/standings?competitions=7&withSeasonsFilter=true" \
  -H "x-api-key: YOUR_API_KEY"

The response includes a seasonFilters array:

{
  "seasonFilters": [
    { "num": 131, "name": "2025/26" },
    { "num": 130, "name": "2024/25" },
    { "num": 129, "name": "2023/24" },
    { "num": 128, "name": "2022/23" }
  ]
}

Request Example

cURL

curl -X GET "https://v1.football.sportsapipro.com/games/season-results?competitions=7&seasonNum=129&page=1&pageSize=100" \
  -H "x-api-key: YOUR_API_KEY"

Response Structure

{
  "seasonNum": 129,
  "seasonName": "2023/24",
  "competition": {
    "id": 7,
    "name": "Premier League",
    "countryId": 1
  },
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "totalGames": 380,
    "totalPages": 4,
    "hasMore": true
  },
  "games": [
    {
      "id": 4567890,
      "competitionId": 7,
      "seasonNum": 129,
      "startTime": "2024-05-19T16:00:00+01:00",
      "statusGroup": 4,
      "homeCompetitor": {
        "id": 110,
        "name": "Manchester City",
        "score": 3
      },
      "awayCompetitor": {
        "id": 127,
        "name": "West Ham",
        "score": 1
      },
      "winner": 1
    }
  ],
  "competitors": [...],
  "countries": [...]
}

Response Fields

Field	Type	Description
seasonNum	number	The requested season number
seasonName	string	Human-readable season name (e.g., “2023/24”)
competition	object	Competition metadata (id, name, countryId)
pagination.page	number	Current page number
pagination.pageSize	number	Results per page
pagination.totalGames	number	Total games in the season
pagination.totalPages	number	Total pages available
pagination.hasMore	boolean	Whether more pages exist
games	array	List of completed match results
competitors	array	Team/competitor reference data
countries	array	Country reference data

Complete Workflow: Fetch All Season Results

JavaScript

async function fetchFullSeasonResults(competitionId, seasonNum) {
  const allGames = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://v1.football.sportsapipro.com/games/season-results?` +
      `competitions=${competitionId}&seasonNum=${seasonNum}&page=${page}&pageSize=100`,
      { headers: { 'x-api-key': 'YOUR_API_KEY' } }
    );
    const data = await response.json();
    
    allGames.push(...data.games);
    hasMore = data.pagination.hasMore;
    page++;
    
    console.log(`Page ${data.pagination.page}/${data.pagination.totalPages} - ${allGames.length} games`);
    
    // Rate limit: pause between requests
    await new Promise(r => setTimeout(r, 100));
  }
  
  console.log(`Total games: ${allGames.length}`);
  return allGames;
}

// Fetch all 380 Premier League games for 2023/24
const results = await fetchFullSeasonResults(7, 129);

Multi-Season Historical Data

For analytics and prediction models requiring multiple seasons:

async function fetchMultiSeasonData(competitionId, numSeasons = 5) {
  // Step 1: Discover available seasons
  const standingsResponse = await fetch(
    `https://v1.football.sportsapipro.com/standings?competitions=${competitionId}&withSeasonsFilter=true`,
    { headers: { 'x-api-key': 'YOUR_API_KEY' } }
  );
  const standingsData = await standingsResponse.json();
  
  const seasons = standingsData.seasonFilters?.slice(0, numSeasons) || [];
  console.log(`Fetching ${seasons.length} seasons...`);
  
  const allData = {};
  
  for (const season of seasons) {
    console.log(`\nFetching ${season.name} (seasonNum: ${season.num})`);
    const games = await fetchFullSeasonResults(competitionId, season.num);
    allData[season.name] = games;
  }
  
  return allData;
}

// Fetch 5 seasons of Premier League data
const historicalData = await fetchMultiSeasonData(7, 5);

Error Handling

Status Code	Description
400	Missing required parameters (competitions or seasonNum)
401	Invalid or missing API key
429	Rate limit exceeded
500	Server error

// 400 Error Response
{
  "error": "Missing required parameters",
  "message": "Both \"competitions\" and \"seasonNum\" parameters are required.",
  "example": "/games/season-results?competitions=7&seasonNum=129"
}

Rate Limiting Notes

• Each call to /games/season-results counts as 1 API request towards your daily quota
• The endpoint internally aggregates multiple upstream calls, but you are only charged once
• For large datasets, add delays between paginated requests to avoid hitting rate limits
• A full Premier League season (380 games) requires 4 API calls at pageSize=100

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

competitions · integer · required

Competition ID (e.g., 7 for Premier League)

Example:

7

seasonNum · integer · required

Season number from /standings?withSeasonsFilter=true (e.g., 129 for 2023/24)

Example:

129

page · integer · default: 1

Page number (default: 1)

Example:

1

pageSize · integer · default: 50

Results per page (default: 50, max: 100)

Required range: x <= 100

Example:

100

showOdds · boolean · default: false

Include betting odds data (default: false)

Response

200

application/json

Season results retrieved successfully

seasonNum · integer

The requested season number

seasonName · string

Human-readable season name (e.g., '2023/24')

competition · object

Competition metadata

Show child attributes

pagination · object

Pagination information

Show child attributes

games · object[]

List of completed match results

Show child attributes

competitors · array

Team/competitor reference data

countries · array

Country reference data