Skip to main content
GET
/
games
/
suggestions
Game Suggestions
curl --request GET \
  --url https://v1.football.sportsapipro.com/games/suggestions \
  --header 'x-api-key: <api-key>'

​
Overview

Returns a list of suggested games based on a reference game. This endpoint is useful for displaying “You might also like” or “Related matches” sections, showing games from similar competitions, teams, or time slots.

​
Query Parameters

​
games
string
Comma-separated list of game IDs to get suggestions for.
​
feedBy
integer
Feed type filter for suggestions:
  • 1: General suggestions
​
matchupId
string
Matchup identifier in format competitorId1-competitorId2-competitionId (e.g., “63-110-9”).
​
lastUpdateId
integer
Last update ID for incremental updates. Use the lastUpdateId from previous response to get only new data.
​
appTypeId
integer
Application type identifier. Auto-resolved by upstream.
​
langId
integer
Language identifier. Auto-resolved by upstream.
​
timezoneName
string
Timezone for date/time values (auto-resolved, or specify e.g., America/New_York).
All startTime fields use ISO 8601 format with a dynamic timezone offset based on the resolved or specified timezone.
​
userCountryId
integer
User’s country for localization. Auto-resolved by upstream.

​
Response Structure

​
suggestedGames
array
Array of suggested game objects.
​
lastUpdateId
integer
Current update ID for incremental fetching.
​
requestedUpdateId
integer
The update ID that was requested.
​
ttl
integer
Cache time-to-live in seconds.
​
sports
array
Sports definitions for referenced games.
​
countries
array
Country information for competitors.
​
competitions
array
Competition details for suggested games.
​
competitors
array
Full competitor information for all teams.
​
games
array
Reference game details (the game suggestions are based on).

​
Status Group Values

ValueStatusDescription
2ScheduledGame not yet started
3LiveGame currently in progress
4EndedGame finished

​
Example Request

curl -X GET "https://v1.football.sportsapipro.com/games/suggestions?games=4609055&feedBy=1&matchupId=63-110-9" \
  -H "x-api-key: YOUR_API_KEY"

​
Example Response

{
  "suggestedGames": [
    {
      "id": 4538916,
      "sportId": 1,
      "competitionId": 7685,
      "seasonNum": 6,
      "stageNum": 5,
      "roundNum": 6,
      "roundName": "Round",
      "competitionDisplayName": "UEFA Conference League",
      "startTime": "2025-12-18T20:00:00+00:00",
      "statusGroup": 3,
      "statusText": "2nd Half",
      "shortStatusText": "2nd Half",
      "gameTimeAndStatusDisplayType": 2,
      "gameTimeDisplay": "85'",
      "homeCompetitor": {
        "id": 1160,
        "countryId": 15,
        "sportId": 1,
        "name": "FC Lausanne-Sport",
        "shortName": "Lausanne-Sport",
        "score": 1.0,
        "isWinner": false,
        "nameForURL": "fc-lausanne-sport",
        "type": 1,
        "popularityRank": 65,
        "imageVersion": 3,
        "color": "#FFFFFF",
        "hasSquad": true
      },
      "awayCompetitor": {
        "id": 228,
        "countryId": 3,
        "sportId": 1,
        "name": "Fiorentina",
        "score": 0.0,
        "isWinner": false,
        "nameForURL": "fiorentina",
        "type": 1,
        "popularityRank": 7510,
        "imageVersion": 2,
        "color": "#693586",
        "hasSquad": true
      },
      "winner": -1,
      "scores": [1.0, 0.0],
      "homeAwayTeamOrder": 1,
      "hasPointByPoint": false,
      "hasVideo": false
    },
    {
      "id": 4452714,
      "sportId": 1,
      "competitionId": 7,
      "competitionDisplayName": "Premier League",
      "startTime": "2025-12-20T12:30:00+00:00",
      "statusGroup": 2,
      "statusText": "Scheduled",
      "shortStatusText": "Sched.",
      "gameTimeAndStatusDisplayType": 0,
      "homeCompetitor": {
        "id": 116,
        "name": "Newcastle United",
        "shortName": "Newcastle Utd",
        "score": -1.0,
        "isWinner": false
      },
      "awayCompetitor": {
        "id": 106,
        "name": "Chelsea",
        "score": -1.0,
        "isWinner": false
      },
      "winner": -1,
      "scores": [-1.0, -1.0]
    }
  ],
  "lastUpdateId": 5495105662,
  "requestedUpdateId": 5495088283,
  "ttl": 10,
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "competitors": [...],
  "games": [...]
}

​
Use Cases

Display suggested games on match detail pages to keep users engaged. Filter by statusGroup: 3 to show currently live suggested matches.

​
Upcoming Matches

Filter by statusGroup: 2 to show scheduled games users might be interested in.

​
Incremental Updates

Use lastUpdateId for real-time updates without refetching all data.

​
Notes

  • Suggestions are based on competition similarity, team popularity, and timing
  • The matchupId format follows awayCompetitorId-homeCompetitorId-competitionId
  • Results include a mix of live, upcoming, and recently finished games
  • Use lastUpdateId for efficient polling during live events

Authorizations

​
x-api-key
string
header
required

Your SportsAPI Pro API key

Query Parameters

​
sports
integer

Sport ID (1 = Football)

Example:

1

Response

200

Game suggestions retrieved successfully