List Games

⚠️ Deprecated — This is a V1 Legacy endpoint. We strongly recommend migrating to the Football V2 API.

Endpoint

GET https://v1.football.sportsapipro.com/games/allscores

Description

Returns all matches for a specified date range. This is the primary endpoint for fetching match data including live scores, scheduled fixtures, completed results, betting odds, and team information.

Built-in TTL: 5 seconds for optimal live data freshness. No manual caching required.

Parameters

Parameter	Type	Required	Default	Description
`startDate`	string	Yes	-	Start date in DD/MM/YYYY format
`endDate`	string	Yes	-	End date in DD/MM/YYYY format
`sports`	number	No	-	Sport ID to filter (1 = Football)
`showOdds`	boolean	No	false	Include betting odds data
`onlyLiveGames`	boolean	No	false	Filter to only live matches
`onlyMajorGames`	boolean	No	false	Filter to major/popular games only
`withTop`	boolean	No	false	Include top competitions marker
`topBookmaker`	number	No	14	Bookmaker ID for odds (14 = Bet365)
`competitions`	string	No	-	⚠️ Not honored - see note below
`lastUpdateId`	number	No	-	For incremental updates (returns only changes since this ID)

The competitions parameter is NOT honored by this endpoint. Even when specified, the response will include games from ALL competitions within the date range. For competition-specific queries, use /games/fixtures or /games/results instead.

The lastUpdateId parameter enables efficient polling by returning only data that changed since the specified update ID. Parameters like appTypeId, langId, timezoneName, and userCountryId are auto-resolved by the upstream service. You can override timezoneName with a specific timezone (e.g., America/New_York). All startTime fields use ISO 8601 format with a dynamic timezone offset.

Date Range Limitations

Wide date ranges may return empty game arrays. When querying large date ranges (e.g., months), the endpoint may return only metadata (competitions, countries) without games. For reliable data retrieval:

Use single-day or small date ranges (1-3 days recommended)
For historical data backfills, use /games/fixtures or /games/results with pagination

Request Examples

curl -X GET "https://v1.football.sportsapipro.com/games/allscores?startDate=18/12/2025&endDate=18/12/2025&sports=1&showOdds=true&onlyMajorGames=true&withTop=true" \
  -H "x-api-key: YOUR_API_KEY"

Timezone Note: The startTime in responses uses ISO 8601 format with a timezone offset that reflects either the auto-resolved user timezone or your specified timezoneName parameter. See Timezone Handling for details.

Response

{
  "lastUpdateId": 5494796687,
  "requestedUpdateId": -1,
  "ttl": 5,
  "summary": {},
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "totalGames": 2,
      "liveGames": 0,
      "nameForURL": "england",
      "imageVersion": 1
    },
    {
      "id": 19,
      "name": "Europe",
      "totalGames": 18,
      "liveGames": 0,
      "nameForURL": "europe",
      "imageVersion": 1,
      "isInternational": true
    }
  ],
  "competitions": [
    {
      "id": 7685,
      "createdAt": "2021-05-31T10:38:19.033",
      "countryId": 19,
      "sportId": 1,
      "name": "UEFA Conference League",
      "shortName": "Conference League",
      "hasStandings": true,
      "hasLiveStandings": false,
      "hasStandingsGroups": false,
      "hasBrackets": true,
      "nameForURL": "uefa-conference-league",
      "totalGames": 18,
      "liveGames": 0,
      "popularityRank": 7655344,
      "hasActiveGames": true,
      "isTop": true,
      "imageVersion": 6,
      "currentStageType": 1,
      "color": "#1D1D1D",
      "currentPhaseName": "Main",
      "currentSeasonNum": 6,
      "currentStageNum": 5,
      "isInternational": true
    }
  ],
  "games": [
    {
      "id": 4631972,
      "sportId": 1,
      "competitionId": 7674,
      "seasonNum": 12,
      "stageNum": 5,
      "groupNum": 2,
      "roundName": "Round",
      "groupName": "3rd Place",
      "competitionDisplayName": "FIFA Arab Cup - 3rd Place",
      "startTime": "2025-12-18T11:00:00+00:00",
      "statusGroup": 3,
      "statusText": "Halftime",
      "shortStatusText": "HT",
      "gameTimeAndStatusDisplayType": 1,
      "justEnded": false,
      "gameTime": 45.0,
      "gameTimeDisplay": "45'",
      "hasLineups": true,
      "hasMissingPlayers": true,
      "hasFieldPositions": true,
      "lineupsStatus": 3,
      "lineupsStatusText": "Lineups",
      "hasTVNetworks": false,
      "hasBetsTeaser": true,
      "winDescription": "Weather delay",
      "odds": {
        "lineId": 1643767251,
        "gameId": 4631972,
        "bookmakerId": 14,
        "lineTypeId": 1,
        "lineType": {
          "id": 1,
          "name": "Full Time Result",
          "shortName": "1X2",
          "title": "Full Time Result"
        },
        "link": "https://www.bet365.com/olp/open-account?affiliate=365_01303661",
        "bookmaker": {
          "id": 14,
          "name": "Bet365",
          "link": "https://extra.bet365.com/features/en/sports-live-streaming",
          "nameForURL": "bet365",
          "actionButton": {
            "link": "https://www.bet365.com/olp/open-account",
            "label": "Bet Now"
          },
          "color": "#007B5B",
          "imageVersion": 3,
          "promotionText": "Sign up at bet365 today"
        },
        "options": [
          {
            "num": 1,
            "name": "1",
            "rate": {
              "decimal": 2.5,
              "fractional": "3/2",
              "american": "+150"
            },
            "oldRate": {
              "decimal": 2.4,
              "fractional": "7/5",
              "american": "+140"
            },
            "originalRate": {
              "decimal": 2.0,
              "fractional": "1/1",
              "american": "+100"
            },
            "prematchRate": {
              "decimal": 2.15,
              "fractional": "7/6",
              "american": "+115"
            },
            "trend": 3
          },
          {
            "num": 2,
            "name": "X",
            "rate": {
              "decimal": 2.2,
              "fractional": "6/5",
              "american": "+120"
            },
            "trend": 1
          },
          {
            "num": 3,
            "name": "2",
            "rate": {
              "decimal": 4.75,
              "fractional": "7/2",
              "american": "+375"
            },
            "trend": 3
          }
        ]
      },
      "homeCompetitor": {
        "id": 5087,
        "countryId": 122,
        "sportId": 1,
        "name": "Saudi Arabia",
        "longName": "Arábia Saudita",
        "symbolicName": "KSA",
        "score": 0.0,
        "isQualified": false,
        "toQualify": false,
        "isWinner": false,
        "nameForURL": "saudi-arabia",
        "type": 2,
        "popularityRank": 14830,
        "imageVersion": 1,
        "rankings": [
          {
            "name": "FIFA",
            "position": 60
          }
        ],
        "color": "#0B5648",
        "awayColor": "#F9FAF9",
        "mainCompetitionId": 5438,
        "hasSquad": true,
        "hasTransfers": false,
        "competitorNum": 1
      },
      "awayCompetitor": {
        "id": 5089,
        "countryId": 124,
        "sportId": 1,
        "name": "UAE",
        "symbolicName": "UAE",
        "score": 0.0,
        "isQualified": false,
        "toQualify": false,
        "isWinner": false,
        "nameForURL": "uae",
        "type": 2,
        "popularityRank": 4681,
        "imageVersion": 1,
        "rankings": [
          {
            "name": "FIFA",
            "position": 67
          }
        ],
        "color": "#FFFFFF",
        "awayColor": "#000000",
        "mainCompetitionId": 5438,
        "hasSquad": true,
        "hasTransfers": false,
        "competitorNum": 2
      },
      "hasStats": true,
      "hasStandings": false,
      "standingsName": "Groups",
      "hasBrackets": true,
      "hasPreviousMeetings": false,
      "hasRecentMatches": false,
      "hasBets": true,
      "hasPlayerBets": false,
      "winner": 0,
      "hasNews": true,
      "hasPointByPoint": false,
      "hasVideo": false
    }
  ],
  "bookmakers": [
    {
      "id": 14,
      "name": "Bet365",
      "link": "https://extra.bet365.com/features/en/sports-live-streaming",
      "nameForURL": "bet365",
      "actionButton": {
        "link": "https://www.bet365.com/olp/open-account",
        "label": "Bet Now"
      },
      "color": "#007B5B",
      "imageVersion": 3,
      "promotionText": "Sign up at bet365 today"
    }
  ]
}

Response Fields

Root Object

Field	Type	Description
`lastUpdateId`	number	Internal versioning ID for incremental updates
`requestedUpdateId`	number	Requested update ID (-1 = latest)
`ttl`	number	Cache TTL in seconds (5 for this endpoint)
`summary`	object	Summary statistics (may be empty)
`sports`	array	Sports definitions array
`countries`	array	Countries with game counts
`competitions`	array	Competition details
`games`	array	Match data with scores and odds
`bookmakers`	array	Available bookmaker information

Game Status Groups

statusGroup	Meaning	Description
1	Scheduled	Not started yet
2	Live (1st Half)	In progress - first half, or pre-match warm-up
3	Live (2nd Half)	In progress - second half, extra time, or halftime
4	Ended	Match finished (Full Time, After Extra Time, After Penalties)
5	Postponed	Match postponed
6	Cancelled	Match cancelled

To filter for all live games, check for statusGroup === 2 || statusGroup === 3. Both values indicate the match is currently in progress.

Game Object Fields

Field	Type	Description
`id`	number	Unique game identifier
`sportId`	number	Sport ID (1 = Football)
`competitionId`	number	Competition this game belongs to
`seasonNum`	number	Season number
`stageNum`	number	Stage number in competition
`groupNum`	number	Group number (for group stage)
`roundNum`	number	Round number
`roundName`	string	Round display name
`groupName`	string	Group name (e.g., “3rd Place”)
`competitionDisplayName`	string	Full competition display name
`startTime`	string	Scheduled start time (ISO 8601 with timezone offset based on auto-resolved or specified timezone)
`statusGroup`	number	Game status category
`statusText`	string	Human-readable status
`shortStatusText`	string	Abbreviated status text
`gameTimeAndStatusDisplayType`	number	Display type for time/status
`justEnded`	boolean	Whether game just finished
`gameTime`	number	Current minute (for live games)
`gameTimeDisplay`	string	Formatted game time (e.g., “45’“)
`hasLineups`	boolean	Whether lineups are available
`hasMissingPlayers`	boolean	Whether missing players info exists
`hasFieldPositions`	boolean	Whether field positions available
`lineupsStatus`	number	Lineup availability status
`lineupsStatusText`	string	Lineup status text
`hasTVNetworks`	boolean	Whether TV info available
`hasBetsTeaser`	boolean	Whether betting teaser available
`winDescription`	string	Special description (delays, etc.)
`odds`	object	Betting odds data
`homeCompetitor`	object	Home team details
`awayCompetitor`	object	Away team details
`hasStats`	boolean	Whether statistics available
`hasStandings`	boolean	Whether standings available
`standingsName`	string	Standings display name
`hasBrackets`	boolean	Whether brackets available
`hasPreviousMeetings`	boolean	Whether H2H data available
`hasRecentMatches`	boolean	Whether recent match data available
`hasBets`	boolean	Whether betting available
`hasPlayerBets`	boolean	Whether player bets available
`winner`	number	Winner (0=none, 1=home, 2=away)
`hasNews`	boolean	Whether news available
`hasVideo`	boolean	Whether video available

Competitor Object

Field	Type	Description
`id`	number	Team ID
`countryId`	number	Country ID
`sportId`	number	Sport ID
`name`	string	Team name
`longName`	string	Extended official name
`symbolicName`	string	3-letter code (e.g., “KSA”)
`score`	number	Current score
`isQualified`	boolean	Whether team qualified
`toQualify`	boolean	Whether team needs to qualify
`isWinner`	boolean	Whether team is winner
`nameForURL`	string	URL-friendly name
`type`	number	Type (1=club, 2=national team)
`popularityRank`	number	Popularity ranking
`imageVersion`	number	Logo image version
`rankings`	array	Official rankings (e.g., FIFA)
`color`	string	Primary brand color (hex)
`awayColor`	string	Away kit color (hex)
`mainCompetitionId`	number	Primary competition ID
`hasSquad`	boolean	Whether squad data available
`hasTransfers`	boolean	Whether transfer data available
`competitorNum`	number	1=home, 2=away

Odds Object

Field	Type	Description
`lineId`	number	Unique betting line ID
`gameId`	number	Associated game ID
`bookmakerId`	number	Bookmaker ID
`lineTypeId`	number	Bet type ID (1=Full Time Result)
`lineType`	object	Bet type details
`link`	string	Bookmaker bet link
`bookmaker`	object	Bookmaker information
`options`	array	Betting options (1, X, 2)

Odds Option Object

Field	Type	Description
`num`	number	Option number (1, 2, 3)
`name`	string	Option label (“1”, “X”, “2”)
`rate`	object	Current odds rate
`oldRate`	object	Previous odds rate
`originalRate`	object	Opening odds rate
`prematchRate`	object	Pre-match odds rate
`trend`	number	1=decreased, 2=unchanged, 3=increased

Odds Rate Formats

Field	Type	Description
`decimal`	number	Decimal odds (e.g., 2.5)
`fractional`	string	UK fractional format (e.g., “3/2”)
`american`	string	American odds (e.g., “+150”)

Country Object

Field	Type	Description
`id`	number	Country ID
`name`	string	Country name
`totalGames`	number	Total games for date range
`liveGames`	number	Currently live games
`nameForURL`	string	URL-friendly name
`imageVersion`	number	Flag image version
`isInternational`	boolean	Whether international (e.g., Europe)

Competition Object

Field	Type	Description
`id`	number	Competition ID
`countryId`	number	Country ID
`sportId`	number	Sport ID
`name`	string	Competition name
`shortName`	string	Abbreviated name
`hasStandings`	boolean	Whether standings available
`hasLiveStandings`	boolean	Whether live standings available
`hasStandingsGroups`	boolean	Whether grouped standings
`hasBrackets`	boolean	Whether brackets available
`nameForURL`	string	URL-friendly name
`totalGames`	number	Total games for date range
`liveGames`	number	Currently live games
`popularityRank`	number	Popularity ranking
`hasActiveGames`	boolean	Whether has active games
`isTop`	boolean	Whether top/featured competition
`imageVersion`	number	Logo image version
`currentStageType`	number	Current stage type
`color`	string	Brand color (hex)
`currentPhaseName`	string	Current phase name
`currentSeasonNum`	number	Current season number
`currentStageNum`	number	Current stage number
`isInternational`	boolean	Whether international competition
`createdAt`	string	Competition creation timestamp

Team Logo URL

https://v1.football.sportsapipro.com/images/competitors/{teamId}?imageVersion={imageVersion}

Country Flag URL

https://v1.football.sportsapipro.com/images/countries/{countryId}?imageVersion={imageVersion}

Competition Logo URL

https://v1.football.sportsapipro.com/images/competitions/{competitionId}?imageVersion={imageVersion}

Authorizations

x-api-key

string

header

required

Your SportsAPI Pro API key

Query Parameters

startDate

string

required

Start date in DD/MM/YYYY format

Example:

"18/12/2025"

endDate

string

required

End date in DD/MM/YYYY format

Example:

"18/12/2025"

sports

integer

Sport ID (1 = Football)

Example:

1

showOdds

boolean

Include betting odds data

Example:

true

onlyMajorGames

boolean

Filter to major/popular games only

Example:

true

Response

200

Games list retrieved successfully

API Reference

⚽ Major Sports

🏈 Team Sports

🥊 Combat & Motorsport

🏓 Racquet & Cue Sports

🏟️ Indoor & Ice Sports

⚽ Football V1

🏀 Basketball V1

🎾 Tennis V1

🏒 Hockey V1

Endpoint

Description

Parameters

Date Range Limitations

Request Examples

Response

Response Fields

Root Object

Game Status Groups

Game Object Fields

Competitor Object

Odds Object

Odds Option Object

Odds Rate Formats

Country Object

Competition Object

Team Logo URL

Country Flag URL

Competition Logo URL

Authorizations

Query Parameters

Response

API Reference

⚽ Major Sports

🏈 Team Sports

🥊 Combat & Motorsport

🏓 Racquet & Cue Sports

🏟️ Indoor & Ice Sports

⚽ Football V1

🏀 Basketball V1

🎾 Tennis V1

🏒 Hockey V1

​Endpoint

​Description

​Parameters

​Date Range Limitations

​Request Examples

​Response

​Response Fields

​Root Object

​Game Status Groups

​Game Object Fields

​Competitor Object

​Odds Object

​Odds Option Object

​Odds Rate Formats

​Country Object

​Competition Object

​Team Logo URL

​Country Flag URL

​Competition Logo URL

Authorizations

Query Parameters

Response

Endpoint

Description

Parameters

Date Range Limitations

Request Examples

Response

Response Fields

Root Object

Game Status Groups

Game Object Fields

Competitor Object

Odds Object

Odds Option Object

Odds Rate Formats

Country Object

Competition Object

Team Logo URL

Country Flag URL

Competition Logo URL