DOCSEARCHbyAlgolia
Submit Docs

espn-service

repository·main·Indexed 20 days ago

https://github.com/pseudo-r/public-espn-api

A production-ready Django REST API (version 1.0.0) for ingesting and querying ESPN sports data. It provides a structured wrapper around ESPN's undocumented public APIs, supporting 17 sports and 139 leagues. The service includes tools for data ingestion via REST endpoints or Django CLI, PostgreSQL and Redis integration, and comprehensive documentation on ESPN API domain routing, known quirks, and endpoint patterns for scores, standings, and athlete statistics.

Tokens
193K
Snippets
281
Records
376
Agent score
70%

What's inside espn-service

  1. Overview of the ESPN Public API Documentation

    main

    This project provides documentation for ESPN's undocumented public APIs. These APIs return JSON data for scores, teams, players, statistics, and more across 17 sports and 139 leagues.

    Key Characteristics:

    • Unofficial: The APIs are not officially supported and may change without notice.
    • No Authentication: Most endpoints are publicly accessible without credentials.
    • Rate Limiting: While no official limits are published, excessive requests may result in being blocked. It is recommended to implement caching and error handling.
    • Internal Domain Fix: Some Core API responses contain $ref URLs using the .pvt domain (e.g., sports.core.api.espn.pvt/...), which is internal and inaccessible. You must replace .pvt with .com to make these URLs functional.

  2. Tennis API Base URLs and League Slugs

    main

    The Tennis API provides professional data from the ATP and WTA tours. You can access data using two different versions of the core API and a specialized Site API for user-friendly data like scores and news.

    Sport Slug: tennis

    Core API Base URLs:

    • v2: https://sports.core.api.espn.com/v2/sports/tennis/
    • v3: https://sports.core.api.espn.com/v3/sports/tennis/

    Available Leagues:

    • ATP: Slug atp | URL: https://sports.core.api.espn.com/v2/sports/tennis/leagues/atp
    • WTA: Slug wta | URL: https://sports.core.api.espn.com/v2/sports/tennis/leagues/wta

  3. Water Polo API Base URLs and Slugs

    main

    The Water Polo API is available via two main versions. The sport slug is water-polo.

    Base URLs:

    • v2: https://sports.core.api.espn.com/v2/sports/water-polo/
    • v3: https://sports.core.api.espn.com/v3/sports/water-polo/

    Available Leagues:

    • NCAA Men's Water Polo: Slug mens-college-water-polo
    • NCAA Women's Water Polo: Slug womens-college-water-polo
    https://sports.core.api.espn.com/v2/sports/water-polo/

  4. Field Hockey API Overview

    main

    The Field Hockey API provides access to women's college field hockey data. It is accessible via two main versions of the Core API and a specialized Site API for user-friendly data like scores and standings.

    Sport slug: field-hockey
    Base URL (v2): https://sports.core.api.espn.com/v2/sports/field-hockey/
    Base URL (v3): https://sports.core.api.espn.com/v3/sports/field-hockey/

  5. Volleyball API Overview

    main

    The Volleyball API provides access to NCAA Men's and Women's volleyball data. It is accessible via two main versions of the Core API and a Site API for user-friendly data like scores and standings.

    Sport slug: volleyball

    Base URLs (v2): https://sports.core.api.espn.com/v2/sports/volleyball/ Base URLs (v3): https://sports.core.api.espn.com/v3/sports/volleyball/

  6. Discover Sports, Leagues, and Teams via Ontology

    main

    Use the ontology endpoints to discover the high-level structure of ESPN's data. These endpoints are designed for discovery and allow you to list all sports, leagues, teams, schools, and venues tracked by the system.

    • List Sports: Use getSports to see all available sports.
    • List Leagues: Use getLeagues to see all leagues across different sports.
    • List Teams: Use getTeams to see all teams.
    • List Schools: Use getSchools for collegiate data.
    • List Venues: Use getVenues to find locations.
    • List Competitions: Use getCompetitions to find competition structures.
    • List Events: Use getEvents for specific event data (supports advanced filtering like start, end, eventsrange, and tournamentId).
    GET https://sports.core.api.espn.com/v2/ontology/sports?page=1&limit=10
GET https://sports.core.api.espn.com/v2/ontology/leagues?page=1&limit=10
GET https://sports.core.api.espn.com/v2/ontology/teams?page=1&limit=10

  7. How to retrieve all NCAA games (College Sports)

    main

    The scoreboard endpoint truncates results by default for college sports. To retrieve the full slate of games for a specific date or date range, you must pass groups=50 (which represents all Division I) along with a high limit (e.g., limit=500).

    Example: .../mens-college-basketball/scoreboard?dates=20260120&groups=50&limit=500

  8. Use numeric league IDs for Rugby API calls

    main

    When making requests for Rugby data, you must use numeric league IDs instead of named slugs. This applies to both the Core API and the Site API endpoints. If you are unsure of the available IDs, you can discover them by querying the leagues endpoint.

    # Get all rugby leagues to discover available numeric IDs
curl "https://sports.core.api.espn.com/v2/sports/rugby/leagues"

  9. Important: MMA Athlete ID handling

    main

    ⚠️ Warning: Athlete IDs in MMA use a different ID space than other sports.

    Do not assume an ID. Always extract the correct ID from the competitor $ref URLs found in event or scoreboard responses. Using IDs from other sports or guessing IDs will result in incorrect data or 404 errors.

  10. How Rugby League League IDs work

    main

    Unlike many other sports that use named slugs (e.g., nrl), Rugby League uses numeric IDs as league slugs. All competitions are served under a single parent slug: 3.

    To discover available numeric IDs for different competitions, use the following endpoint: https://sports.core.api.espn.com/v2/sports/rugby-league/leagues

    https://sports.core.api.espn.com/v2/sports/rugby-league/leagues/3

  12. How to discover cricket series and match summaries

    main

    To get detailed match information, follow this two-step workflow using the Personalized Header API and the Web API Summary endpoint.

    1. Discover Active Series

    Call the Personalized Header API to find active cricket series/competitions.

    Endpoint: GET https://site.api.espn.com/apis/personalized/v2/scoreboard/header?sport=cricket&region=in&tz=Asia/Calcutta

    From the response, look at sports[0].leagues[]. Each league object contains:

    • id: The numeric series/league ID. Use this as the {leagueId} in the next step.
    • events[]: A list of live/upcoming matches. Each event has an id. Use this as the {eventId} in the next step.
    • name: The series name (e.g., "India tour of England 2026").
    • isTournament: Boolean indicating if it is a league/tournament format.

    2. Get Full Match Summary/Scorecard

    Use the IDs discovered in step 1 to fetch the full scorecard via the Web API.

    Endpoint: GET https://site.web.api.espn.com/apis/site/v2/sports/cricket/{leagueId}/summary?event={eventId}&lang=en&region=in

    Key Response Fields:

    • matchcards: Contains the innings-by-innings scorecard.
    • rosters: Contains both squads.
    • leaders: Contains top batters and bowlers.
    • news, videos, article: Related media and content.
    # 1. List active cricket series
curl "https://site.api.espn.com/apis/personalized/v2/scoreboard/header?sport=cricket&region=in&tz=Asia/Calcutta"

# 2. Match summary (using example IDs: leagueId 23694, event 1490237)
curl "https://site.web.api.espn.com/apis/site/v2/sports/cricket/23694/summary?contentorigin=espn&event=1490237&lang=en&region=in"