Matches & Best Odds

Paginated match lists, sport shortcuts, smart bets, and best-odds (max) feeds

Match List

GET /api/v1/matches
GET /api/v1/matches?sport=football&status=all&page=1&perPage=50
GET /api/v1/matches?sport=tennis&status=inplay&perPage=20

Primary discovery endpoint — paginated across all 17 sports.

Param	Type	Default	Description
sport	string	(all)	Sport slug (e.g. football, tennis)
status	string	all	all, inplay, prematch, finished
page	number	1	Page number
perPage	number	50	Results per page (max 150)
startDate	string	today	ISO 8601 (e.g. 2026-06-11T00:00:00Z)
endDate	string	today	ISO 8601

Response

{
  "generatedAt": "2026-04-05 00:25:04",
  "totalMatches": 1440,
  "totalPages": 29,
  "currentPage": 1,
  "matches": [
    {
      "id": 9798283,
      "homeTeam": "Mexico",
      "homeTeamId": 6,
      "homeTeamAbbr": "MEX",
      "awayTeam": "South Africa",
      "awayTeamId": 1487,
      "awayTeamAbbr": "RSA",
      "matchDate": "2026-06-11 19:00:00+00",
      "status": null,
      "inplay": false,
      "homeScore": null,
      "awayScore": null,
      "sportId": 1,
      "sportSlug": "football",
      "leagueId": 3,
      "leagueRound": "Round 1",
      "hasSpecialOffer": false
    }
  ]
}

Field	Description
id	Match ID — feed into /api/v1/match/{id}
inplay	true while the match is live
leagueId	Use for standings, top scorers, outrights
matchDate	ISO 8601 with timezone

Cache TTL: 30s for status=inplay, 2 minutes otherwise.

---

Sport Shortcuts

Convenience aliases that wrap the match list endpoint:

Path	Equivalent to
/api/v1/{sport}/live	?sport={sport}&status=inplay
/api/v1/{sport}/today	?sport={sport}&status=all (today)
/api/v1/{sport}/tomorrow	tomorrow’s date window
/api/v1/{sport}/yesterday	yesterday’s date window
/api/v1/{sport}/all	full default window

Examples

GET /api/v1/football/live
GET /api/v1/tennis/today
GET /api/v1/basketball/tomorrow
GET /api/v1/ice-hockey/yesterday

Response shape is identical to Match List.

---

Smart Bets

GET /api/v1/matches/smart-bets
GET /api/v1/matches/smart-bets?sport=football&status=all

Same parameters and shape as /matches, with a smart-betting data overlay attached to each match.

Cache TTL: 2 minutes.

---

Best Odds (Max)

GET /api/v1/odds/max
GET /api/v1/odds/max?sport=football&status=all&page=1&perPage=50

Returns the best (maximum) odds for each match across every bookmaker, grouped by market.

Param	Type	Default	Description
sport	string	(all)	Sport slug
status	string	all	all or inplay (only these two are supported on /odds/max)
page	number	1	Page
perPage	number	50	Per page
startDate	string	today	ISO 8601
endDate	string	today	ISO 8601

Response

{
  "generatedAt": "2026-04-05 00:00:00",
  "totalMatches": 500,
  "totalPages": 10,
  "currentPage": 1,
  "odds": {
    "9791299": {
      "100": {
        "odds": [
          { "o1": 2.15, "o2": 3.45, "oX": 3.20, "bid": 170, "bookie_name": "Stake.com" }
        ]
      }
    }
  }
}

The odds object is keyed by match ID, then by market ID (100 = 1X2).

Cache TTL: 30s for status=inplay, 2 minutes otherwise.

---

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://v4.football.sportsapipro.com/api/v1/football/today"