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 20+ 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 API Reference

1000+ leagues including Premier League, La Liga, Champions League

Basketball API Reference

50+ leagues including NBA, EuroLeague, WNBA

All Sports Overview

Tennis, Hockey, Baseball, Cricket, MMA, Esports & more

Authentication

All endpoints require authentication via the x-api-key header. The same API key works across all 20+ 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 upstream service 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();

// startTime reflects your auto-detected timezone
data.games?.forEach(match => {
  console.log(`${match.homeCompetitor.name} vs ${match.awayCompetitor.name}`);
  console.log(`Kick-off: ${match.startTime}`);
});

Parsing Timezone-Aware Responses

The 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

All date/time values are returned in ISO 8601 format with the resolved timezone offset:

{
  "startTime": "2026-01-07T19:30:00+00:00"
}

The offset (e.g., +00:00, -05:00, +09:00) reflects either the auto-resolved timezone or the manually specified one.

Example: Same Match in Different Timezones

The same match displays different startTime values depending on the timezone:

{
  "id": 4609057,
  "competitionDisplayName": "Premier League",
  "startTime": "2026-01-07T20:00:00+00:00",
  "homeCompetitor": { "name": "Arsenal" },
  "awayCompetitor": { "name": "Chelsea" }
}

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

All responses follow a consistent structure with built-in caching information:

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

Common Response Fields

Field	Type	Description
`lastUpdateId`	number	Internal versioning ID for incremental updates
`requestedUpdateId`	number	Update ID requested by client (-1 = latest data)
`ttl`	number	Time To Live in seconds—how long to cache the response

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.

Available Endpoints by Sport

Football API Endpoints

Games

Live scores, fixtures, results, and match stats

Competitions

1000+ leagues and tournaments

Athletes

Player stats, game logs, and profiles

Standings

League tables and rankings

Betting

Odds, lines, and predictions

Search

Find players, teams, and competitions

Basketball API Endpoints

Games

Live scores, fixtures, and results

Competitions

NBA, EuroLeague, WNBA, and 50+ leagues

Athletes

Player stats and game logs

Standings

Conference and division rankings

Betting

Lines, props, and predictions

Search

Find players and teams

Rate Limiting

Rate limits are shared across all 20+ 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

Explore the Football API endpoints

Basketball V2 API

Explore the Basketball API endpoints

API Reference

⚽ Major Sports

🏈 Team Sports

🥊 Combat & Motorsport

🏓 Racquet & Cue Sports

🏟️ Indoor & Ice Sports

⚽ Football V1

🏀 Basketball V1

🎾 Tennis V1

🏒 Hockey V1

​Base URLs

Football API (V2)

Basketball API (V2)

Any Sport (V2)

​Quick Links

Football API Reference

Basketball API Reference

All Sports Overview

​Authentication

​Auto-Resolved Parameters

​Timezone Handling

​How Auto-Resolution Works

​Timezone source Field

​Manual Override

​Code Examples

​Parsing Timezone-Aware Responses

​Date/Time Format in Responses

​Example: Same Match in Different Timezones

​Common Timezone Examples

​Response Structure

​Common Response Fields

​Available Endpoints by Sport

​Football API Endpoints

Games

Competitions

Athletes

Standings

Betting

Search

​Basketball API Endpoints

Games

Competitions

Athletes

Standings

Betting

Search

​Rate Limiting

​Sport IDs Reference

​Next Steps

Quickstart Guide

Football V2 API

Basketball V2 API

Base URLs

Quick Links

Authentication

Auto-Resolved Parameters

Timezone Handling

How Auto-Resolution Works

Timezone `source` Field

Manual Override

Code Examples

Parsing Timezone-Aware Responses

Date/Time Format in Responses

Example: Same Match in Different Timezones

Common Timezone Examples

Response Structure

Common Response Fields

Available Endpoints by Sport

Football API Endpoints

Basketball API Endpoints

Rate Limiting

Sport IDs Reference

Next Steps