Get Predictions

Retrieve match predictions with voting data and betting odds

GET /games/predictions

Game Predictions

cURL

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

Overview

Returns upcoming matches with user predictions/voting data and betting odds from bookmakers. This endpoint is ideal for displaying prediction contests, voting polls, and odds comparisons.

Cache TTL: 300 seconds (5 minutes)

Parameters

sports · integer

Filter by sport ID. Default: 1 (Football)

topBookmaker · integer

Preferred bookmaker ID for odds display (e.g., 14 for Bet365)

Parameters appTypeId, langId, timezoneName, and userCountryId are automatically 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.

Response Structure

lastUpdateId · integer

Internal versioning ID for caching or incremental updates

requestedUpdateId · integer

Update ID requested by client. Value of -1 means “retrieve the latest data”

ttl · integer

Time To Live in seconds (300 for this endpoint)

games · array

Array of games with prediction data

Show Prediction Game Object

id · integer

Unique game identifier

sportId · integer

Sport identifier (1 = Football)

competitionId · integer

Competition reference ID

competitionDisplayName · string

Formatted competition name with stage info

startTime · string

ISO 8601 match start time with timezone offset (based on auto-resolved or specified timezone)

statusText · string

Current match status (e.g., “Scheduled”)

homeCompetitor · object

Home team with full competitor details

awayCompetitor · object

Away team with full competitor details

promotedPredictions · object

Prediction and voting data

Show Promoted Predictions

predictions · array

Array of prediction types (e.g., “Who Will Win?”)

Show Prediction Object

id · integer

Prediction identifier

type · integer

Prediction type (1 = match winner)

title · string

Display title (e.g., “Who Will Win?”)

showVotes · boolean

Whether to display vote counts

totalVotes · integer

Total number of user votes

odds · object

Betting odds from bookmaker

options · array

Voting options with counts and percentages

hasLineups · boolean

Whether lineup data is available

lineupsStatus · integer

Lineup status (2 = Probable Lineups)

hasBets · boolean

Whether betting data is available

sports · array

Referenced sport objects

countries · array

Referenced country objects with game counts

competitions · array

Referenced competition objects

competitors · array

Referenced competitor/team objects

Request Example

cURL

curl -X GET "https://v1.football.sportsapipro.com/games/predictions?sports=1&topBookmaker=14" \
  -H "x-api-key: YOUR_API_KEY"

Response Example

{
  "lastUpdateId": 5494785914,
  "requestedUpdateId": -1,
  "ttl": 300,
  "sports": [
    {
      "id": 1,
      "name": "Football",
      "nameForURL": "football",
      "drawSupport": true,
      "imageVersion": 1
    }
  ],
  "countries": [
    {
      "id": 1,
      "name": "England",
      "totalGames": 1,
      "liveGames": 0,
      "nameForURL": "england",
      "imageVersion": 1
    }
  ],
  "competitions": [
    {
      "id": 7,
      "countryId": 1,
      "sportId": 1,
      "name": "Premier League",
      "shortName": "EPL",
      "hasStandings": true,
      "nameForURL": "premier-league",
      "totalGames": 1,
      "popularityRank": 92710242,
      "imageVersion": 12,
      "color": "#075C9C"
    }
  ],
  "competitors": [
    {
      "id": 108,
      "countryId": 1,
      "sportId": 1,
      "name": "Liverpool",
      "symbolicName": "LIV",
      "nameForURL": "liverpool",
      "type": 1,
      "popularityRank": 53493,
      "imageVersion": 22,
      "color": "#E41E2C"
    }
  ],
  "games": [
    {
      "id": 4452713,
      "sportId": 1,
      "competitionId": 7,
      "competitionDisplayName": "Premier League",
      "startTime": "2025-12-20T17:30:00+00:00",
      "statusGroup": 2,
      "statusText": "Scheduled",
      "shortStatusText": "Sched.",
      "hasLineups": true,
      "lineupsStatus": 2,
      "lineupsStatusText": "Probable Lineups",
      "hasBets": true,
      "homeCompetitor": {
        "id": 114,
        "name": "Tottenham",
        "symbolicName": "TOT",
        "score": -1.0,
        "imageVersion": 6,
        "color": "#FFFFFF"
      },
      "awayCompetitor": {
        "id": 108,
        "name": "Liverpool",
        "symbolicName": "LIV",
        "score": -1.0,
        "imageVersion": 22,
        "color": "#E41E2C"
      },
      "promotedPredictions": {
        "predictions": [
          {
            "id": 978987317,
            "type": 1,
            "title": "Who Will Win?",
            "showVotes": true,
            "totalVotes": 7340,
            "odds": {
              "lineId": 1625719943,
              "gameId": 4452713,
              "bookmakerId": 14,
              "lineTypeId": 1,
              "lineType": {
                "id": 1,
                "name": "Full Time Result",
                "shortName": "1X2",
                "title": "Full Time Result"
              },
              "bookmaker": {
                "id": 14,
                "name": "Bet365",
                "color": "#007B5B",
                "imageVersion": 3
              },
              "options": [
                {
                  "num": 1,
                  "name": "1",
                  "rate": {
                    "decimal": 3.5,
                    "fractional": "5/2",
                    "american": "+250"
                  },
                  "trend": 3
                },
                {
                  "num": 2,
                  "name": "X",
                  "rate": {
                    "decimal": 3.75,
                    "fractional": "11/4",
                    "american": "+275"
                  },
                  "trend": 3
                },
                {
                  "num": 3,
                  "name": "2",
                  "rate": {
                    "decimal": 2.0,
                    "fractional": "1/1",
                    "american": "+100"
                  },
                  "trend": 1
                }
              ]
            },
            "options": [
              {
                "num": 1,
                "name": "Tottenham",
                "vote": {
                  "count": 1541,
                  "percentage": 21
                }
              },
              {
                "num": 2,
                "name": "Draw",
                "vote": {
                  "count": 734,
                  "percentage": 10
                }
              },
              {
                "num": 3,
                "name": "Liverpool",
                "vote": {
                  "count": 5065,
                  "percentage": 69
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Key Fields Reference

Prediction Options

Field	Type	Description
num	integer	Option number (1=Home, 2=Draw, 3=Away)
name	string	Team name or “Draw”
vote.count	integer	Number of user votes
vote.percentage	integer	Percentage of total votes

Odds Rate Object

Field	Type	Description
decimal	number	Decimal odds format (e.g., 2.0)
fractional	string	UK fractional format (e.g., “1/1”)
american	string	American odds format (e.g., “+100”)

Odds Trend Values

Value	Meaning
1	Odds decreased (shortened)
2	Odds unchanged
3	Odds increased (drifted)

Use Cases

• Build prediction/voting contests for upcoming matches
• Display community sentiment with vote percentages
• Show betting odds comparisons from bookmakers
• Create match preview pages with crowd predictions
• Track odds movements with trend indicators

Authorizations

x-api-key · string · header · required

Your SportsAPI Pro API key

Query Parameters

gameId · integer · required

Game identifier

Example:

4609057

Response

200

Game predictions retrieved successfully