API Reference Overview - SportsAPI Pro

Base URLs

Access our multi-sport API through dedicated sport-specific endpoints. The V2 Enhanced API is available for all 25+ sports:

Football API (V2)

https://v2.football.sportsapipro.com

Basketball API (V2)

https://v2.basketball.sportsapipro.com

Any Sport (V2)

https://v2.{sport}.sportsapipro.com

V2 Enhanced API offers 120+ endpoints with advanced data: shotmaps, AI insights, player heatmaps, tournament brackets, manager/referee data, and WebSocket real-time support. Explore V2 →

Legacy V1 endpoints remain available for backward compatibility. See the V1 Legacy (Deprecated) section for V1 documentation.

Quick Links

Football V2

147+ endpoints — Premier League, La Liga, Champions League & 1000+ leagues

Basketball V2

115 endpoints: NBA, EuroLeague, WNBA & 50+ leagues

Tennis V2

88 endpoints: ATP, WTA rankings, draws & point-by-point

Cricket V2

IPL, Test cricket, T20 leagues & live ball-by-ball

Ice Hockey V2

NHL, KHL, SHL & 30+ leagues worldwide

Browse All 25 Sports ↓

Team, racquet, combat, motorsport & more

Authentication

All endpoints require authentication via the x-api-key header. The same API key works across all 25+ sports APIs:

curl -X GET "https://v2.football.sportsapipro.com/competitions" \
  -H "x-api-key: YOUR_API_KEY"

Your API key is shared across all sports. Rate limits and usage are tracked across your entire account, not per sport.

Auto-Resolved Parameters

The API automatically determines the user’s language, timezone, and country based on request context. You do not need to specify default values for these parameters—they are resolved automatically.

The following parameters are auto-resolved but can be overridden if needed:

Parameter	Auto-Resolved	Description
`appTypeId`	Yes	Application type identifier (default: 5)
`langId`	Yes	Language ID (1 = English)
`timezoneName`	Yes	Timezone for date/time values (see below)
`userCountryId`	Yes	User’s country for localization

Timezone Handling

Timezone is automatically resolved based on the user’s country. You can also override it by passing the timezoneName query parameter.

How Auto-Resolution Works

The V2 API uses a country-based mechanism to determine the user’s timezone:

Country detection — Cloudflare identifies the user’s country from their IP address (via the CF-IPCountry header).
Country → Timezone mapping — The backend maps the detected country code (e.g., DE → Europe/Berlin, US → America/New_York) to the primary IANA timezone for that country.
Applied to responses — All date/time fields in the response use the resolved timezone offset.

If the country cannot be determined (e.g., VPN, internal traffic), the API falls back to UTC.

Timezone `source` Field

API responses include a source field in the timezone metadata indicating how the timezone was resolved:

Source	Meaning
`"auto"`	Timezone was auto-resolved from the user’s detected country
`"manual"`	Timezone was explicitly set via the `timezoneName` parameter
`"default"`	Fallback to UTC (country could not be detected)

Manual Override

You can override auto-resolution by passing the timezoneName query parameter with any valid IANA timezone identifier:

curl -H "x-api-key: YOUR_API_KEY" \
  "https://v2.football.sportsapipro.com/api/live"

Code Examples

Use these examples to integrate timezone handling into your application. The API auto-resolves timezone from your IP, or you can override it manually.

const API_KEY = 'YOUR_API_KEY';

// Timezone is auto-resolved from your IP location
const response = await fetch('https://v2.football.sportsapipro.com/api/live', {
  headers: { 'x-api-key': API_KEY }
});

const data = await response.json();

// startTimestamp reflects your auto-detected timezone
data.events?.forEach(match => {
  console.log(`${match.homeTeam} vs ${match.awayTeam}`);
  console.log(`Kick-off: ${new Date(match.startTimestamp * 1000).toISOString()}`);
});

V1 Legacy: Parsing ISO 8601 Responses

V2 uses Unix timestamps (startTimestamp) — see the next section. This ISO 8601 parsing guide applies only to V1 endpoints which return date strings with timezone offsets.

The V1 API returns ISO 8601 dates with timezone offsets (e.g., 2026-01-07T15:00:00-05:00). Here’s how to parse them correctly:

// The offset is embedded in the string — Date() handles it automatically
const startTime = '2026-01-07T15:00:00-05:00';
const date = new Date(startTime);

console.log(date.toISOString());           // "2026-01-07T20:00:00.000Z" (UTC)
console.log(date.toLocaleString('en-US')); // Localized to user's browser timezone

// Convert to a specific display timezone
console.log(date.toLocaleString('en-US', { timeZone: 'America/Chicago' }));
// "1/7/2026, 2:00:00 PM" (Central Time)

Don’t strip the offset! Always parse the full ISO 8601 string including the offset (e.g., -05:00). Stripping it and treating the time as UTC will give incorrect results.

Date/Time Format in Responses

The V2 API returns timestamps as Unix epoch integers (startTimestamp). Convert to your desired display format:

{
  "startTimestamp": 1736280600
}

Use the timezoneName query parameter to control how schedule endpoints group matches by date.

Example: Same Match in Different Timezones

The same match returns the same startTimestamp regardless of timezone. The timezoneName parameter affects date-based grouping, not the timestamp value:

{
  "id": 4609057,
  "tournament": "Premier League",
  "startTimestamp": 1736280000,
  "homeTeam": "Arsenal",
  "awayTeam": "Chelsea"
}

Convert startTimestamp to display times in any timezone:

Timezone	Display Time
UTC	2026-01-07 20:00:00
America/New_York	2026-01-07 15:00:00
America/Los_Angeles	2026-01-07 12:00:00
Europe/Berlin	2026-01-07 21:00:00
Asia/Tokyo	2026-01-08 05:00:00

The same match (8:00 PM UTC kickoff) displays as 3:00 PM in New York, 12:00 PM in Los Angeles, 9:00 PM in Berlin, and 5:00 AM the next day in Tokyo.

Common Timezone Examples

Region	timezoneName Value
UTC/GMT	`UTC` or `Etc/GMT`
US Eastern	`America/New_York`
US Pacific	`America/Los_Angeles`
UK	`Europe/London`
Central Europe	`Europe/Berlin`
Japan	`Asia/Tokyo`
Australia Sydney	`Australia/Sydney`
India	`Asia/Kolkata`

Best Practice: For server-to-server integrations, explicitly specify timezoneName to ensure consistent behavior regardless of server location. For client-facing applications, rely on auto-resolution for the best user experience.

V1 Legacy Note: V1 endpoints also support the timezoneName parameter for manual override, but auto-resolution may behave differently. For the most reliable timezone handling, use the V2 API.

Response Structure

V2 API Response Format

The V2 API returns data in a clean envelope with an events array:

{
  "success": true,
  "count": 48,
  "events": [
    {
      "id": 12647890,
      "slug": "arsenal-chelsea",
      "tournament": { "name": "Premier League", "uniqueTournament": { "id": 17 } },
      "homeTeam": { "id": 42, "name": "Arsenal" },
      "awayTeam": { "id": 38, "name": "Chelsea" },
      "homeScore": { "current": 2, "period1": 1, "period2": 1 },
      "awayScore": { "current": 1, "period1": 0, "period2": 1 },
      "status": { "code": 100, "type": "finished" },
      "startTimestamp": 1720375200
    }
  ]
}

V1 Legacy Response Format

V1 endpoints use a different envelope with games, sports, and competitions arrays:

{
  "lastUpdateId": 5494749399,
  "requestedUpdateId": -1,
  "ttl": 300,
  "sports": [...],
  "countries": [...],
  "competitions": [...],
  "games": [...]
}

Common Response Fields

Field	Version	Type	Description
`success`	V2	boolean	Whether the request succeeded
`count`	V2	number	Number of items returned
`events`	V2	array	Array of event/match objects
`lastUpdateId`	V1	number	Internal versioning ID for incremental updates
`ttl`	V1	number	Time To Live in seconds — recommended cache duration

Each endpoint has its own built-in cache with a defined TTL. No manual caching or client-side caching is required. The TTL value indicates the recommended cache duration.

Browse by Sport

Explore all 25 V2 sports organized by category. Each sport has its own dedicated subdomain and full endpoint documentation.

Popular Sports

Football

147+ endpoints — 1000+ leagues, shotmaps, AI insights, WebSocket

Basketball

115 endpoints: NBA, EuroLeague, box scores, playoff brackets

Tennis

88 endpoints: ATP/WTA rankings, draws, point-by-point

Cricket

IPL, Test, T20 — ball-by-ball, scorecards, player stats

Ice Hockey

NHL, KHL, SHL — period scoring, penalty stats, playoffs

Team Sports

Baseball

MLB, NPB, KBO — innings, pitch stats, box scores

American Football

NFL, NCAA — quarter scoring, drive charts, player stats

Rugby

Six Nations, Rugby Championship, Super Rugby

Handball

Champions League, World Championship, Olympic handball

Volleyball

FIVB, Champions League — set-based scoring

Futsal

FIFA Futsal World Cup, continental leagues

Water Polo

Olympic water polo, European championships

Racquet & Precision Sports

Table Tennis

ITTF World Tour, Olympic table tennis

Badminton

BWF World Tour, All England, Olympic badminton

Snooker

World Championship, UK Championship, The Masters

Darts

PDC World Championship, Premier League Darts

Beach Volleyball

FIVB Beach Pro Tour, Olympic beach volleyball

Specialty Sports

MMA

UFC, Bellator, PFL

Motorsport

F1, MotoGP, NASCAR

Cycling

Tour de France, Giro, Vuelta

Esports

CS2, LoL, Dota 2, Valorant

Aussie Rules

AFL, state leagues

Floorball

IFF World Championship

Bandy

World Championship, Elitserien

Minifootball

WMF competitions

Rate Limiting

Rate limits are shared across all 25+ sports APIs. Your daily quota applies to your total usage across Football, Basketball, Tennis, and every other sport.

Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Your daily request limit
`X-RateLimit-Remaining`	Remaining requests today
`X-RateLimit-Reset`	Unix timestamp when limit resets

See Rate Limits for more details.

Sport IDs Reference

Use these IDs with the sports parameter to filter by sport type:

ID	Sport	API Status
1	Football (Soccer)	✅ Available
2	Basketball	✅ Available
3	Tennis	✅ Available
4	Ice Hockey	✅ Available
5	Handball	✅ Available
6	American Football	✅ Available
7	Baseball	✅ Available
8	Volleyball	✅ Available
10	Cycling	✅ Available
11	Motorsport	✅ Available
12	Rugby	✅ Available
15	Table Tennis	✅ Available
19	Snooker	✅ Available
22	Darts	✅ Available
26	Water Polo	✅ Available
29	Futsal	✅ Available
31	Badminton	✅ Available
32	Bandy	✅ Available
34	Beach Volleyball	✅ Available
62	Cricket	✅ Available
64	Minifootball	✅ Available
71	Aussie Rules	✅ Available
72	Esports	✅ Available
74	Floorball	✅ Available
117	MMA	✅ Available

Each sport has its own dedicated API subdomain (e.g., v2.football.sportsapipro.com, v2.basketball.sportsapipro.com, v2.tennis.sportsapipro.com). The sports parameter is used for filtering within multi-sport endpoints like /countries.

Next Steps

Quickstart Guide

Get up and running in minutes

Football V2 API

Basketball V2 API

NBA, EuroLeague & 50+ leagues

Tennis V2 API

Rankings, draws & point-by-point

Cricket V2 API

IPL, Test & T20 coverage

Ice Hockey V2 API

NHL, KHL & 30+ leagues

​Base URLs

Football API (V2)

Basketball API (V2)

Any Sport (V2)

​Quick Links

Football V2

Basketball V2

Tennis V2

Cricket V2

Ice Hockey V2

Browse All 25 Sports ↓

​Authentication

​Auto-Resolved Parameters

​Timezone Handling

​How Auto-Resolution Works

​Timezone source Field

​Manual Override

​Code Examples

​V1 Legacy: Parsing ISO 8601 Responses

​Date/Time Format in Responses

​Example: Same Match in Different Timezones

​Common Timezone Examples

​Response Structure

​V2 API Response Format

​V1 Legacy Response Format

​Common Response Fields

​Browse by Sport

​Popular Sports

Football

Basketball

Tennis

Cricket

Ice Hockey

​Team Sports

Baseball

American Football

Rugby

Handball

Volleyball

Futsal

Water Polo

​Racquet & Precision Sports

Table Tennis

Badminton

Snooker

Darts

Beach Volleyball

​Specialty Sports

MMA

Motorsport

Cycling

Esports

Aussie Rules

Floorball

Bandy

Minifootball

​Rate Limiting

​Sport IDs Reference

​Next Steps

Quickstart Guide

Football V2 API

Basketball V2 API

Tennis V2 API

Cricket V2 API

Ice Hockey V2 API

Base URLs

Quick Links

Authentication

Auto-Resolved Parameters

Timezone Handling

How Auto-Resolution Works

Timezone `source` Field

Manual Override

Code Examples

V1 Legacy: Parsing ISO 8601 Responses

Date/Time Format in Responses

Example: Same Match in Different Timezones

Common Timezone Examples

Response Structure

V2 API Response Format

V1 Legacy Response Format

Common Response Fields

Browse by Sport

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

Rate Limiting

Sport IDs Reference

Next Steps