SportsDatabase.io
Documentation

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.

View pricing tiersGo to developer portal

1. Create an account

Sign up via the portal using email + password or OAuth. Free tier includes generous read access.

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/teams
    GETFreeSample only

    Find teams by full or partial name.

  • Search Events/v1/search/events
    GETPaid / Enterprise

    Locate events by title with optional filters for season, date, or canonical asset filename.

  • Search Players/v1/search/players
    GETFreeSample only

    Search for players by primary or alternate name fields.

  • Search Venues/v1/search/venues
    GETPaid / 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/league
    GETFreeSample only

    Fetch canonical league metadata by ID.

  • Lookup League Table/v1/lookup/league-table
    GETPaid / Enterprise

    Return current league standings, optionally filtered by season.

  • Lookup Team/v1/lookup/team
    GETFreeSample only

    Pull team metadata by ID.

  • Lookup Team Equipment/v1/lookup/team-equipment
    GETPaid / Enterprise

    Retrieve historical and current kits associated with a team.

  • Lookup Player/v1/lookup/player
    GETPaid / Enterprise

    Return detailed player profile by ID.

  • Lookup Player Honours/v1/lookup/player-honours
    GETPaid / Enterprise

    List trophies and awards earned by a player.

  • Lookup Player Former Teams/v1/lookup/player-former-teams
    GETPaid / Enterprise

    Enumerate historical teams for a given player.

  • Lookup Player Milestones/v1/lookup/player-milestones
    GETPaid / Enterprise

    Return milestone events for a player.

  • Lookup Player Contracts/v1/lookup/player-contracts
    GETPaid / Enterprise

    Fetch contractual history for a player.

  • Lookup Player Results/v1/lookup/player-results
    GETPaid / Enterprise

    Return match-level results for a player.

  • Lookup Event/v1/lookup/event
    GETPaid / Enterprise

    Fetch event metadata by ID.

  • Lookup Event Results/v1/lookup/event-results
    GETPaid / Enterprise

    Return player or team results for an event.

  • Lookup Event Lineup/v1/lookup/event-lineup
    GETPaid / Enterprise

    List starting lineups and substitutes for an event.

  • Lookup Event Timeline/v1/lookup/event-timeline
    GETPaid / Enterprise

    Retrieve play-by-play timeline for an event.

  • Lookup Event Statistics/v1/lookup/event-stats
    GETPaid / Enterprise

    Return aggregated event statistics (team and player).

  • Lookup Event Broadcasts/v1/lookup/event-broadcasts
    GETPaid / Enterprise

    List domestic and international broadcasts for an event.

  • Lookup Venue/v1/lookup/venue
    GETPaid / 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/sports
    GETFreeSample only

    Return all sports supported by the catalog.

  • Sports Directory (canonical)/v1/sports
    GETPaid / Enterprise

    Lists active sports from the new catalog with SportData IDs.

  • All Countries/v1/list/countries
    GETFreeSample only

    List all supported countries.

  • All Leagues/v1/list/leagues
    GETPaid / Enterprise

    Return all leagues in the catalog.

  • List Leagues By Country/Sport/v1/list/leagues/by-region
    GETPaid / Enterprise

    Filter leagues by country and sport name.

  • List Seasons/v1/list/seasons
    GETPaid / Enterprise

    Return seasons for a given league ID with optional asset flags.

  • List Teams/v1/list/teams
    GETPaid / Enterprise

    List teams within a league by name/country/sport or by ID.

  • List Players/v1/list/players
    GETPaid / Enterprise

    Return players for a given team ID.

  • Leagues Directory (canonical)/v1/leagues
    GETPaid / Enterprise

    Lists leagues with SportData IDs and optional sport filters.

  • Teams Directory (canonical)/v1/teams
    GETPaid / Enterprise

    Lists teams with canonical IDs and league/sport filters.

  • Players Directory (canonical)/v1/players
    GETPaid / 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/next
    GETFreeSample only

    Return upcoming events for a team.

  • Events Directory (canonical)/v1/events
    GETPaid / Enterprise

    Query canonical events joined to SportData IDs for sports, leagues, and teams.

  • Team Previous Events/v1/schedule/team/previous
    GETPaid / Enterprise

    Return recent events for a team.

  • League Next Events/v1/schedule/league/next
    GETPaid / Enterprise

    Next events across a league.

  • League Previous Events/v1/schedule/league/previous
    GETPaid / Enterprise

    Recent results across a league.

  • Schedule By Day/v1/schedule/by-day
    GETPaid / Enterprise

    Fetch events on a given date with optional sport/league filters.

  • Schedule By Season/v1/schedule/by-season
    GETPaid / Enterprise

    All events for a league season.

  • Schedule TV Guide/v1/schedule/tv
    GETPaid / Enterprise

    Television schedule for a date with optional filters.

Video

Highlight discovery endpoints sourcing verified YouTube links with optional filters by league or sport.

  • Event Highlights/v1/video/highlights
    GETFreeSample only

    Return YouTube highlight clips for the given date, optionally filtered.

v2

V2 API

Next-generation JSON API with clean RESTful paths, richer filtering, and improved caching. Recommended for new integrations.

Search

REST-style search endpoints for quickly finding entities via slugified strings.

  • Search League/api/v2/json/search/league/{query}
    GETFreeSample only

    Search leagues by slugified text.

  • Search Team/api/v2/json/search/team/{query}
    GETFreeSample only

    Search teams via slugified text.

  • Search Player/api/v2/json/search/player/{query}
    GETPaid / Enterprise

    Search players via slugified text string.

  • Search Event/api/v2/json/search/event/{query}
    GETPaid / Enterprise

    Search events with slug-like text including teams and date.

  • Search Venue/api/v2/json/search/venue/{query}
    GETPaid / Enterprise

    Search venues via slugified text.

Lookup

RESTful resource lookups keyed off unique IDs.

  • Lookup League/api/v2/json/lookup/league/{leagueId}
    GETFreeSample only

    League detail by ID.

  • Lookup Team/api/v2/json/lookup/team/{teamId}
    GETPaid / Enterprise

    Team detail by ID.

  • Lookup Team Equipment/api/v2/json/lookup/team_equipment/{teamId}
    GETPaid / Enterprise

    Historical and current equipment for a team.

  • Lookup Player/api/v2/json/lookup/player/{playerId}
    GETPaid / Enterprise

    Player detail by ID.

  • Lookup Player Contracts/api/v2/json/lookup/player_contracts/{playerId}
    GETPaid / Enterprise

    Contract data for a player.

  • Lookup Player Results/api/v2/json/lookup/player_results/{playerId}
    GETPaid / Enterprise

    Match results for a player.

  • Lookup Player Honours/api/v2/json/lookup/player_honours/{playerId}
    GETPaid / Enterprise

    Honours for a player.

  • Lookup Player Milestones/api/v2/json/lookup/player_milestones/{playerId}
    GETPaid / Enterprise

    Milestone events for a player.

  • Lookup Player Former Teams/api/v2/json/lookup/player_teams/{playerId}
    GETPaid / Enterprise

    Historical team affiliations for a player.

  • Lookup Event/api/v2/json/lookup/event/{eventId}
    GETPaid / Enterprise

    Event detail by ID.

  • Lookup Event Lineup/api/v2/json/lookup/event_lineup/{eventId}
    GETPaid / Enterprise

    Player lineups for an event.

  • Lookup Event Results/api/v2/json/lookup/event_results/{eventId}
    GETPaid / Enterprise

    Results for an event.

  • Lookup Event Statistics/api/v2/json/lookup/event_stats/{eventId}
    GETPaid / Enterprise

    Event statistics (team and player).

  • Lookup Event Timeline/api/v2/json/lookup/event_timeline/{eventId}
    GETPaid / Enterprise

    Chronological timeline for an event.

  • Lookup Event TV Schedule/api/v2/json/lookup/event_tv/{eventId}
    GETPaid / Enterprise

    Broadcast schedule for an event.

  • Lookup Event Highlights/api/v2/json/lookup/event_highlights/{eventId}
    GETPaid / Enterprise

    YouTube highlights for an event.

  • Lookup Venue/api/v2/json/lookup/venue/{venueId}
    GETPaid / Enterprise

    Venue detail by ID.

List

Collection endpoints returning multiple entities in a single call.

  • List League Teams/api/v2/json/list/teams/{leagueId}
    GETFreeSample only

    All teams in a league.

  • List League Seasons/api/v2/json/list/seasons/{leagueId}
    GETPaid / Enterprise

    Season metadata for a league.

  • List League Season Posters/api/v2/json/list/seasonposters/{leagueId}
    GETPaid / Enterprise

    Poster assets for league seasons.

  • List Team Players/api/v2/json/list/players/{teamId}
    GETPaid / Enterprise

    Players for a team.

Filter

TV event filters with tidy RESTful paths.

  • Filter TV Events by Date/api/v2/json/filter/tv/day/{date}
    GETFreeSample only

    TV events for a specific date.

  • Filter TV Events by Country/api/v2/json/filter/tv/country/{country}
    GETPaid / Enterprise

    TV events filtered by broadcaster country.

  • Filter TV Events by Sport/api/v2/json/filter/tv/sport/{sport}
    GETPaid / Enterprise

    TV events filtered by sport.

  • Filter TV Events by Channel/api/v2/json/filter/tv/channel/{channel}
    GETPaid / Enterprise

    TV events filtered by channel name.

  • Filter TV Events by Channel ID/api/v2/json/filter/tv/channelid/{channelId}
    GETPaid / Enterprise

    TV events filtered by channel ID.

All

Utility endpoints that return entire collections, ideal for bootstrapping caches.

  • All Countries/api/v2/json/all/countries
    GETFreeSample only

    List all supported countries.

  • All Sports/api/v2/json/all/sports
    GETPaid / Enterprise

    List all sports.

  • All Leagues/api/v2/json/all/leagues
    GETPaid / Enterprise

    List all leagues.

Schedule

High-performance schedule endpoints with consistent pagination.

  • Next 10 League Events/api/v2/json/schedule/next/league/{leagueId}
    GETFreeSample only

    Upcoming events for a league.

  • Previous 10 League Events/api/v2/json/schedule/previous/league/{leagueId}
    GETPaid / Enterprise

    Most recent league events.

  • Next 10 Team Events/api/v2/json/schedule/next/team/{teamId}
    GETPaid / Enterprise

    Upcoming team events.

  • Previous 10 Team Events/api/v2/json/schedule/previous/team/{teamId}
    GETPaid / Enterprise

    Recent team events.

  • Next 10 Venue Events/api/v2/json/schedule/next/venue/{venueId}
    GETPaid / Enterprise

    Upcoming venue events.

  • Previous 10 Venue Events/api/v2/json/schedule/previous/venue/{venueId}
    GETPaid / Enterprise

    Recent venue events.

  • Full Team Season Schedule/api/v2/json/schedule/full/team/{teamId}
    GETPaid / Enterprise

    Complete season schedule for a team.

  • Full League Season Schedule/api/v2/json/schedule/league/{leagueId}/{season}
    GETPaid / Enterprise

    Complete season schedule for a league.

Livescores

Live event status endpoints with low-latency caching.

  • Livescore by Sport/api/v2/json/livescore/{sport}
    GETPaid / Enterprise

    Current live scores for a sport.

  • Livescore by League/api/v2/json/livescore/{leagueId}
    GETPaid / Enterprise

    Live scores for a league.

  • Livescore All/api/v2/json/livescore/all
    GETFreeSample only

    All live events across sports.

Submission guidelines

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.