1. Create an account
Sign up via the portal using email + password or OAuth. Free tier includes generous read access.
Build on SportsDatabase APIs
Everything you need to explore the sports taxonomy, subscribe to live events, and contribute back to the community. All endpoints share consistent pagination, filtering, and authentication conventions.
2. Generate an API key
Head to the Portal → API Keys tab. Keys are hashed, scoped, and revokable with rate-limit insights.
3. Authenticate requests
Send requests with the `x-api-key` header. OAuth client credentials and signed JWTs coming soon.
v1
V1 API
Legacy endpoints backed by our PHP-compatible gateway. Use these for backwards compatibility and broad dataset coverage.
Search
String-based discovery endpoints. Use these to locate IDs before using faster lookup routes. All endpoints return entities plus their catalog IDs.
- Search Teams/v1/search/teamsGETFreeSample only
Find teams by full or partial name.
- Search Events/v1/search/eventsGETPaid / Enterprise
Locate events by title with optional filters for season, date, or canonical asset filename.
- Search Players/v1/search/playersGETFreeSample only
Search for players by primary or alternate name fields.
- Search Venues/v1/search/venuesGETPaid / Enterprise
Lookup venues by primary or alternate name.
Lookup
ID-driven endpoints optimized for quick fetches once catalog IDs are known. Ideal for rendering detail pages or syncing records.
- Lookup League/v1/lookup/leagueGETFreeSample only
Fetch canonical league metadata by ID.
- Lookup League Table/v1/lookup/league-tableGETPaid / Enterprise
Return current league standings, optionally filtered by season.
- Lookup Team/v1/lookup/teamGETFreeSample only
Pull team metadata by ID.
- Lookup Team Equipment/v1/lookup/team-equipmentGETPaid / Enterprise
Retrieve historical and current kits associated with a team.
- Lookup Player/v1/lookup/playerGETPaid / Enterprise
Return detailed player profile by ID.
- Lookup Player Honours/v1/lookup/player-honoursGETPaid / Enterprise
List trophies and awards earned by a player.
- Lookup Player Former Teams/v1/lookup/player-former-teamsGETPaid / Enterprise
Enumerate historical teams for a given player.
- Lookup Player Milestones/v1/lookup/player-milestonesGETPaid / Enterprise
Return milestone events for a player.
- Lookup Player Contracts/v1/lookup/player-contractsGETPaid / Enterprise
Fetch contractual history for a player.
- Lookup Player Results/v1/lookup/player-resultsGETPaid / Enterprise
Return match-level results for a player.
- Lookup Event/v1/lookup/eventGETPaid / Enterprise
Fetch event metadata by ID.
- Lookup Event Results/v1/lookup/event-resultsGETPaid / Enterprise
Return player or team results for an event.
- Lookup Event Lineup/v1/lookup/event-lineupGETPaid / Enterprise
List starting lineups and substitutes for an event.
- Lookup Event Timeline/v1/lookup/event-timelineGETPaid / Enterprise
Retrieve play-by-play timeline for an event.
- Lookup Event Statistics/v1/lookup/event-statsGETPaid / Enterprise
Return aggregated event statistics (team and player).
- Lookup Event Broadcasts/v1/lookup/event-broadcastsGETPaid / Enterprise
List domestic and international broadcasts for an event.
- Lookup Venue/v1/lookup/venueGETPaid / Enterprise
Fetch venue metadata by ID.
List
Bulk collection endpoints returning arrays of entities. Useful for populating dropdowns or caching reference data.
- All Sports/v1/list/sportsGETFreeSample only
Return all sports supported by the catalog.
- Sports Directory (canonical)/v1/sportsGETPaid / Enterprise
Lists active sports from the new catalog with SportData IDs.
- All Countries/v1/list/countriesGETFreeSample only
List all supported countries.
- All Leagues/v1/list/leaguesGETPaid / Enterprise
Return all leagues in the catalog.
- List Leagues By Country/Sport/v1/list/leagues/by-regionGETPaid / Enterprise
Filter leagues by country and sport name.
- List Seasons/v1/list/seasonsGETPaid / Enterprise
Return seasons for a given league ID with optional asset flags.
- List Teams/v1/list/teamsGETPaid / Enterprise
List teams within a league by name/country/sport or by ID.
- List Players/v1/list/playersGETPaid / Enterprise
Return players for a given team ID.
- Leagues Directory (canonical)/v1/leaguesGETPaid / Enterprise
Lists leagues with SportData IDs and optional sport filters.
- Teams Directory (canonical)/v1/teamsGETPaid / Enterprise
Lists teams with canonical IDs and league/sport filters.
- Players Directory (canonical)/v1/playersGETPaid / Enterprise
Lists players with canonical SportData IDs and team/league filters.
Schedule
Endpoints covering upcoming and historical fixtures at team, league, and date granularity. Useful for broadcast guides and archives.
- Team Next Events/v1/schedule/team/nextGETFreeSample only
Return upcoming events for a team.
- Events Directory (canonical)/v1/eventsGETPaid / Enterprise
Query canonical events joined to SportData IDs for sports, leagues, and teams.
- Team Previous Events/v1/schedule/team/previousGETPaid / Enterprise
Return recent events for a team.
- League Next Events/v1/schedule/league/nextGETPaid / Enterprise
Next events across a league.
- League Previous Events/v1/schedule/league/previousGETPaid / Enterprise
Recent results across a league.
- Schedule By Day/v1/schedule/by-dayGETPaid / Enterprise
Fetch events on a given date with optional sport/league filters.
- Schedule By Season/v1/schedule/by-seasonGETPaid / Enterprise
All events for a league season.
- Schedule TV Guide/v1/schedule/tvGETPaid / Enterprise
Television schedule for a date with optional filters.
Stat Leaders
Computed statistics and rankings across teams, leagues, and sports. These endpoints analyze event data to generate real-time leaderboards and performance metrics. PRO/ENTERPRISE tier required.
- Stats Overview/v1/stats/overviewGETPaid / Enterprise
Summary of top performers across all stat categories including win rate, scoring, clean sheets, and goal difference.
- Team Win Rate Leaders/v1/stats/teams/win-rateGETPaid / Enterprise
Teams ranked by winning percentage with W/L/D breakdown.
- Team Goals Scored Leaders/v1/stats/teams/goals-scoredGETPaid / Enterprise
Teams ranked by total goals/points scored.
- Team Clean Sheets Leaders/v1/stats/teams/clean-sheetsGETPaid / Enterprise
Teams ranked by number of clean sheets (shutouts).
- Team Goal Difference Leaders/v1/stats/teams/goal-differenceGETPaid / Enterprise
Teams ranked by goal difference (scored minus conceded).
- Team Form Leaders/v1/stats/teams/formGETPaid / Enterprise
Teams ranked by recent form (performance over last N games).
- Team Home Advantage/v1/stats/teams/home-advantageGETPaid / Enterprise
Teams ranked by home vs away win rate differential.
- Team Scoring Efficiency/v1/stats/teams/scoring-efficiencyGETPaid / Enterprise
Teams ranked by average points/goals scored per game.
- Team Defensive Efficiency/v1/stats/teams/defensive-efficiencyGETPaid / Enterprise
Teams ranked by fewest points/goals conceded per game.
- Team Consistency/v1/stats/teams/consistencyGETPaid / Enterprise
Teams ranked by scoring consistency (lowest variation in scores).
- Team Blowouts/v1/stats/teams/blowoutsGETPaid / Enterprise
Teams ranked by average margin of victory.
- Team Streaks/v1/stats/teams/streaksGETPaid / Enterprise
Teams ranked by current winning and unbeaten streaks.
- Head-to-Head/v1/stats/head-to-headGETPaid / Enterprise
Historical head-to-head record between two teams.
- Most Active Leagues/v1/stats/leagues/most-activeGETPaid / Enterprise
Leagues ranked by event count over a time period.
- Highest Scoring Leagues/v1/stats/leagues/highest-scoringGETPaid / Enterprise
Leagues ranked by average goals/points per game.
- Most Competitive Leagues/v1/stats/leagues/most-competitiveGETPaid / Enterprise
Leagues ranked by average margin (lower = more competitive).
- Sports Overview/v1/stats/sports/overviewGETPaid / Enterprise
Statistics aggregated by sport including event counts and activity.
Venues
Stadium and arena data including geolocation, capacity, and event history. Pro/Enterprise tier only.
- List Venues/v1/venuesGETPaid / Enterprise
List all venues with optional filtering by country, city, or coordinate availability.
- Get Venue/v1/venues/:idOrSlugGETPaid / Enterprise
Fetch detailed venue data by ID or slug.
- Venue Events/v1/venues/:idOrSlug/eventsGETPaid / Enterprise
Get events held at a venue.
- Nearby Venues/v1/venues/nearbyGETPaid / Enterprise
Find venues near a geographic point using haversine distance.
Officials
Match official data including referees, umpires, and judges. Includes sport-specific career statistics. Pro/Enterprise tier only.
- List Officials/v1/officialsGETPaid / Enterprise
List all officials with optional filtering by category, nationality, or status.
- Get Official/v1/officials/:idOrSlugGETPaid / Enterprise
Fetch detailed official profile by ID or slug, including sport-specific career stats.
- Search Officials/v1/officials/searchGETPaid / Enterprise
Search officials by name or nationality.
- Cricket Elite Panel/v1/officials/cricket/elite-panelGETPaid / Enterprise
Get ICC Elite Panel umpires and match referees with career statistics.
Video
Highlight discovery endpoints sourcing verified YouTube links with optional filters by league or sport.
- Event Highlights/v1/video/highlightsGETFreeSample only
Return YouTube highlight clips for the given date, optionally filtered.
Provide canonical data with sources
Each submission should cite reputable references and match SportData catalog conventions. Moderators review for accuracy, completeness, and consistency with existing taxonomy entries.
- catalogIdNUM 2–8 (required)Canonical SportID.
- nameSTR 3–80 (required)Display name.
- slugSLUG (required)URL identifier (lowercase with hyphens).
- summarySTR 20–400 (required)Concise overview of the sport.
- governingBodySTR ≤120Primary federation.
- originYearINT 1600–2100First recorded play.
- primaryEquipmentSTR ≤120Key equipment.
- popularRegionsLIST ≤10Comma or newline separated regions.
- sourcesURL[] ≤5Supporting references.