Game Suggestions

GET

games

suggestions

Game Suggestions

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/games/suggestions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/games/suggestions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/games/suggestions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/games/suggestions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

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

string

Comma-separated list of game IDs to get suggestions for.

integer

Feed type filter for suggestions:

1: General suggestions

string

Matchup identifier in format competitorId1-competitorId2-competitionId (e.g., “63-110-9”).

integer

Last update ID for incremental updates. Use the lastUpdateId from previous response to get only new data.

integer

Application type identifier. Auto-resolved.

integer

Language identifier. Auto-resolved.

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.

integer

User’s country for localization. Auto-resolved.

Response Structure

array

Array of suggested game objects.

Show Suggested Game Object

integer

Unique game identifier.

integer

Sport type ID.

integer

Competition identifier.

integer

Season number.

integer

Stage number within the competition.

integer

Group number (for group stage competitions).

integer

Round number (for league competitions).

string

Display name for the round (e.g., “Round”).

string

Formatted competition name with stage info.

string

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

integer

Game status category:

1: Not Started / Scheduled
2: Scheduled (pre-match)
3: Live / In Progress
4: Ended / Finished
5: Cancelled
6: Postponed
8: Abandoned

string

Full status description (e.g., “2nd Half”, “Scheduled”, “After ET”).

string

Abbreviated status text.

integer

Display type for game time:

0: Show start time
1: Show final status
2: Show live minute

string

Current game minute for live matches (e.g., “85’”).

object

Home team information including id, name, score, colors, and metadata.

object

Away team information including id, name, score, colors, and metadata.

integer

Winner indicator:

-1: No winner yet / Draw
1: Home team won
2: Away team won

array

Array with [homeScore, awayScore]. Value of -1.0 indicates not started.

integer

Team display order preference.

boolean

Whether point-by-point data is available.

boolean

Whether video content is available.

integer

Current update ID for incremental fetching.

integer

The update ID that was requested.

integer

Cache time-to-live in seconds.

array

Sports definitions for referenced games.

array

Country information for competitors.

array

Competition details for suggested games.

array

Full competitor information for all teams.

array

Reference game details (the game suggestions are based on).

Status Group Values

Value	Status	Description
2	Scheduled	Game not yet started
3	Live	Game currently in progress
4	Ended	Game finished

Example Request

curl -X GET "https://api.sportsapipro.com/v1/football/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.

Live Games Carousel

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

Last modified on June 29, 2026

Game Suggestions

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

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.sportsapipro.com/v1/football/games/suggestions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sportsapipro.com/v1/football/games/suggestions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sportsapipro.com/v1/football/games/suggestions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sportsapipro.com/v1/football/games/suggestions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Overview

Query Parameters

Response Structure

Status Group Values

Example Request

Example Response

Use Cases

Live Games Carousel

Upcoming Matches

Incremental Updates

Notes

Authorizations

Query Parameters

Response

​Overview

​Query Parameters

​Response Structure

​Status Group Values

​Example Request

​Example Response

​Use Cases

​Related Matches Widget

​Live Games Carousel

​Upcoming Matches

​Incremental Updates

​Notes

Authorizations

Query Parameters

Response

Overview

Query Parameters

Response Structure

Status Group Values

Example Request

Example Response

Use Cases

Related Matches Widget

Live Games Carousel

Upcoming Matches

Incremental Updates

Notes