### List Sports Data by ID (API V2) Source: https://www.thesportsdb.com/documentation/index Retrieves lists of related sports entities based on a unique ID. Examples include listing all teams in a league, all seasons for a league, or all players for a team. The API returns up to 100 results per list. ```HTTP /api/v2/json/list/teams/4328 ``` ```HTTP /api/v2/json/list/seasons/4328 ``` ```HTTP /api/v2/json/list/players/133604 ``` -------------------------------- ### List Leagues by Country and Sport Source: https://www.thesportsdb.com/documentation/index Retrieve a list of leagues for a specific country and sport. ```APIDOC ## GET /api/v1/json/:key/search_all_leagues.php ### Description List all the leagues in a country for a specific sport. ### Method GET ### Endpoint /api/v1/json/:key/search_all_leagues.php ### Parameters #### Query Parameters - **c** (String) - Required - The country name. - **s** (String) - Required - The sport name. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/search_all_leagues.php?c=England&s=Soccer ``` ### Response #### Success Response (200) - **countrys** (Array) - An array of league objects matching the criteria. #### Response Example ```json { "countrys": [ { "idLeague": "4328", "strLeague": "English Premier League", "strSport": "Soccer", "strCountry": "England", "strGender": "Male", "strLeagueAlternate": "Premier League" } ] } ``` ``` -------------------------------- ### V1 Authentication Source: https://www.thesportsdb.com/documentation/index V1 API uses a simple authentication process by appending an API key to the base URL. A free key '123' is available for testing. ```APIDOC ## V1 Authentication v1 of the API has a very simple authentication process. Simply use the base URL above and append the number `/123/` to the URL for the test key or replace with your premium API key. ### Using the free key: ``` https://www.thesportsdb.com/api/v1/json/123/searchteams.php?t=Arsenal ``` ### Using your premium API key: ``` https://www.thesportsdb.com/api/v1/json/YOUR_API_KEY_GOES_HERE/searchteams.php?t=Arsenal ``` ``` -------------------------------- ### List All Countries Source: https://www.thesportsdb.com/documentation/index Retrieve a list of all supported geographical countries. ```APIDOC ## GET /api/v1/json/:key/all_countries.php ### Description List all the geographical countries supported on the website. ### Method GET ### Endpoint /api/v1/json/:key/all_countries.php ### Parameters None ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/all_countries.php ``` ### Response #### Success Response (200) - **countries** (Array) - An array of country objects. #### Response Example ```json { "countries": [ { "idCountry": "1", "name_en": "England", "name_ред": "England" } ] } ``` ``` -------------------------------- ### Image Handling Source: https://www.thesportsdb.com/documentation/index Access various image types (JPEG, PNG) for events, players, and teams. Preview images can be accessed by appending size modifiers to the image URL. ```APIDOC ## Images Our site has a huge amount of images for things like events, players and teams. Most are fan created. There are 2 types of images available. JPEG fanart and transparent PNG mostly used for badges and logos. You can see the different types of artwork and sizes on this page. You can access any image from the front-end using the image URL from the returned JSON data. ### Preview Images Most of the time you won't want to download the original large image, just get a small preview. This is possible simple by appending '/medium', '/small', '/tiny' onto the end URL. This will give you a smaller version. **Original Image URL:** `/league/fanart/xpwsrw1421853005.jpg` **Preview Image URLs:** - Medium 500px: `/league/fanart/xpwsrw1421853005.jpg/medium` - Small 250px: `/league/fanart/xpwsrw1421853005.jpg/small` - Tiny 50px: `/league/fanart/xpwsrw1421853005.jpg/tiny` ``` -------------------------------- ### List All Sports Source: https://www.thesportsdb.com/documentation/index Retrieve a list of all supported sports categories. ```APIDOC ## GET /api/v1/json/:key/all_sports.php ### Description List all the sport categories supported on the website. ### Method GET ### Endpoint /api/v1/json/:key/all_sports.php ### Parameters None ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/all_sports.php ``` ### Response #### Success Response (200) - **sports** (Array) - An array of sport objects. #### Response Example ```json { "sports": [ { "idSport": "1", "strSport": "Soccer", "strFormat": "T", "strSportThumb": "https://www.thesportsdb.com/images/media/sport/thumb/soccer.jpg", "strSportDescription": "Soccer is a team sport played with a spherical ball between two teams of 11 players. It is played by roughly 250 million players in over 200 countries and dependencies, making it the world's most popular sport." } ] } ``` ``` -------------------------------- ### List All Leagues Source: https://www.thesportsdb.com/documentation/index Retrieve a list of all leagues supported on TheSportsDB. ```APIDOC ## GET /api/v1/json/:key/all_leagues.php ### Description List all the leagues on TheSportsDB. ### Method GET ### Endpoint /api/v1/json/:key/all_leagues.php ### Parameters None ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/all_leagues.php ``` ### Response #### Success Response (200) - **leagues** (Array) - An array of league objects. #### Response Example ```json { "leagues": [ { "idLeague": "4328", "strLeague": "English Premier League", "strSport": "Soccer", "strGatherer": "", "strCurrentSeason": "2023/2024", "intFormedYear": "1992", "dateFirstEvent": "1992-08-15", "strCountry": "England", "strGender": "Male", "strLeagueAlternate": "Premier League", "strHasLeagues": "English League", "strDivision": "1", "strLogo": "https://www.thesportsdb.com/images/media/league/logo/wxq2bp1425059126.png", "strBanner": "https://www.thesportsdb.com/images/media/league/banner/z9o3p11590949487.jpg", "strFanart1": "https://www.thesportsdb.com/images/media/league/fanart/rqqyqr1425059126.jpg", "strFanart2": "https://www.thesportsdb.com/images/media/league/fanart/rqqyqr1425059126.jpg", "strFanart3": "https://www.thesportsdb.com/images/media/league/fanart/rqqyqr1425059126.jpg", "strFanart4": "https://www.thesportsdb.com/images/media/league/fanart/rqqyqr1425059126.jpg", "strTwitter": "@premierleague", "strWebsite": "http://www.premierleague.com/" } ] } ``` ``` -------------------------------- ### List Seasons by League Source: https://www.thesportsdb.com/documentation/index Retrieve a list of all available seasons for a specific league ID. ```APIDOC ## GET /api/v1/json/:key/search_all_seasons.php ### Description List all the seasons available for a specific league ID. ### Method GET ### Endpoint /api/v1/json/:key/search_all_seasons.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the league. - **poster** (Integer) - Optional - Include poster images. - **badge** (Integer) - Optional - Include badge images. - **description** (Integer) - Optional - Include season descriptions. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/search_all_seasons.php?id=4328 https://www.thesportsdb.com/api/v1/json/123/search_all_seasons.php?id=4328&poster=1 https://www.thesportsdb.com/api/v1/json/123/search_all_seasons.php?id=4328&badge=1 https://www.thesportsdb.com/api/v1/json/123/search_all_seasons.php?id=4328&description=1 ``` ### Response #### Success Response (200) - **seasons** (Array) - An array of season objects for the specified league. #### Response Example ```json { "seasons": [ { "strSeason": "2002/2003", "idSeason": "39117", "strStartDate": "2002-08-17", "strEndDate": "2003-05-11", "strFullSeasons": "2002/2003", "strSeasonYear": "2002" } ] } ``` ``` -------------------------------- ### API Base URLs Source: https://www.thesportsdb.com/documentation/index The root URL for making API requests. Choose between V1 or V2 based on your needs and subscription. ```APIDOC ## API Base URLs The Base URL is a crucial element for making API calls, enabling you to clearly specify the root URL(s) for API requests. When making API calls, you combine the base URL with the specific endpoint path to form the complete request URL. ### v1 Base URL ``` https://www.thesportsdb.com/api/v1/json ``` ### v2 Base URL ``` https://www.thesportsdb.com/api/v2/json ``` ``` -------------------------------- ### List Teams Source: https://www.thesportsdb.com/documentation/index Retrieve a list of teams based on league name, country, sport, or team ID. ```APIDOC ## GET /api/v1/json/:key/search_all_teams.php ### Description List all the teams in a specific league by the leagues name, country and sport or ID. ### Method GET ### Endpoint /api/v1/json/:key/search_all_teams.php ### Parameters #### Query Parameters - **l** (String) - Optional - The league name. - **s** (String) - Optional - The sport name. - **c** (String) - Optional - The country name. - **id** (Integer) - Optional - The team ID. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/search_all_teams.php?l=English_Premier_League https://www.thesportsdb.com/api/v1/json/123/search_all_teams.php?s=Soccer&c=Spain ``` ### Response #### Success Response (200) - **teams** (Array) - An array of team objects matching the criteria. #### Response Example ```json { "teams": [ { "idTeam": "133604", "strTeam": "Manchester United", "strSport": "Soccer", "strLeague": "English Premier League", "strLeague2": "Premier League", "strFormedYear": "1878", "strCurrentSeason": "2023/2024", "intLoved": "1290", "strStadium": "Old Trafford", "strKeywords": "Manchester,United,Man Utd,Red Devils", "strCountry": "England", "strTeamBadge": "https://www.thesportsdb.com/images/media/team/badge/ypw2f61594772033.png", "strTeamFanart1": "https://www.thesportsdb.com/images/media/team/fanart/ypw2f61594772033.jpg", "strTeamFanart2": "https://www.thesportsdb.com/images/media/team/fanart/ypw2f61594772033.jpg", "strTeamFanart3": "https://www.thesportsdb.com/images/media/team/fanart/ypw2f61594772033.jpg", "strTeamFanart4": "https://www.thesportsdb.com/images/media/team/fanart/ypw2f61594772033.jpg", "strTeamBanner": "https://www.thesportsdb.com/images/media/team/banner/ypw2f61594772033.jpg", "strDescriptionEN": "Manchester United Football Club is a professional football club based in Old Trafford, Greater Manchester, England. The club competes in the Premier League, the top tier of English football. Founded in 1878 as Newton Heath LYR Football Club, Manchester United began playing professionally in 1892 and was renamed Manchester United in 1902.", "strWebsite": "http://www.manutd.com/", "strRSS": "", "strAlternate": "Man Utd,Red Devils" } ] } ``` ``` -------------------------------- ### List API Endpoints Source: https://www.thesportsdb.com/documentation/index Endpoints for listing multiple entities related to leagues and teams. ```APIDOC ## GET /api/v2/json/list/teams/{idLeague} ### Description List all teams in a particular league by its unique ID. ### Method GET ### Endpoint /api/v2/json/list/teams/{idLeague} ### Parameters #### Path Parameters - **idLeague** (Integer) - Required - The unique ID of the league. ### Response #### Success Response (200) - **teams** (Array) - An array containing the teams belonging to the specified league. #### Response Example { "example": "{\"teams\":[{\"idTeam\": \"133604\", \"strTeam\": \"Manchester United\", ...}]}" } ``` ```APIDOC ## GET /api/v2/json/list/seasons/{idLeague} ### Description List all seasons available for a league using its unique ID. ### Method GET ### Endpoint /api/v2/json/list/seasons/{idLeague} ### Parameters #### Path Parameters - **idLeague** (Integer) - Required - The unique ID of the league. ### Response #### Success Response (200) - **seasons** (Array) - An array containing the available seasons for the league. #### Response Example { "example": "{\"seasons\":[{\"yearFrom\": \"2022\", \"yearTo\": \"2023\"}]}" } ``` ```APIDOC ## GET /api/v2/json/list/players/{idTeam} ### Description Lookup for all the players for a team using its unique ID. ### Method GET ### Endpoint /api/v2/json/list/players/{idTeam} ### Parameters #### Path Parameters - **idTeam** (Integer) - Required - The unique ID of the team. ### Response #### Success Response (200) - **player** (Array) - An array containing the players belonging to the specified team. #### Response Example { "example": "{\"player\":[{\"idPlayer\": \"34172575\", \"strPlayer\": \"Harry Kane\", ...}]}" } ``` -------------------------------- ### Schedule League Next Source: https://www.thesportsdb.com/documentation/index Retrieves the next upcoming events for a specific league using its ID. ```APIDOC ## GET /eventsnextleague.php ### Description See the next upcoming events for a team using the league ID. ### Method GET ### Endpoint /api/v1/json/123/eventsnextleague.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the league. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/eventsnextleague.php?id=4328 ``` ### Response #### Success Response (200) - **Events** (Array) - A list of upcoming events for the specified league. ``` -------------------------------- ### Lookup Venue Source: https://www.thesportsdb.com/documentation/index Retrieve information about a venue using its unique ID. ```APIDOC ## GET /api/v1/json/:key/lookupvenue.php ### Description Lookup a venue using its ID. ### Method GET ### Endpoint /api/v1/json/:key/lookupvenue.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the venue to look up. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/lookupvenue.php?id=16163 ``` ### Response #### Success Response (200) - **venues** (Array) - An array of venue objects. #### Response Example ```json { "venues": [ { "idVenue": "16163", "strVenue": "Old Trafford", "strVenueLocation": "Manchester", "strVenueCapacity": "76000", "strVenueWebsite": "http://www.manutd.com", "strVenueFanart": "https://www.thesportsdb.com/images/media/venue/fanart/vwhwvt1425088015.jpg", "strVenueThumb": "https://www.thesportsdb.com/images/media/venue/thumb/vwhwvt1425088015.jpg" } ] } ``` ``` -------------------------------- ### List Players by Team Source: https://www.thesportsdb.com/documentation/index Retrieve a list of all players who play for a specific team using the team's ID. ```APIDOC ## GET /api/v1/json/:key/lookup_all_players.php ### Description List all the Players who play for a team by the teams ID. ### Method GET ### Endpoint /api/v1/json/:key/lookup_all_players.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the team. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/lookup_all_players.php?id=133604 ``` ### Response #### Success Response (200) - **player** (Array) - An array of player objects belonging to the specified team. #### Response Example ```json { "player": [ { "idPlayer": "34145271", "strPlayer": "David de Gea", "strTeam": "Manchester United", "strSport": "Soccer", "strPosition": "Goalkeeper", "dateBorn": "1990-11-07", "strNationality": "Spanish", "strTeam2": "Spain", "strCollege": null, "strSalary": null, "strWage": null, "strThumb": "https://www.thesportsdb.com/images/media/player/thumb/david-de-gea-1000608.jpg", "strCutoutImage": "https://www.thesportsdb.com/images/media/player/cutout/david-de-gea-1000608.png", "strBanner": "https://www.thesportsdb.com/images/media/player/banner/david-de-gea-1000608.jpg", "strDescriptionEN": "David de Gea Quintana is a Spanish professional footballer who plays as a goalkeeper for Premier League club Manchester United and the Spain national team.", "strFacebook": "https://www.facebook.com/DavidDeGeaOfficial", "strTwitter": "@D_DeGea", "strInstagram": "https://www.instagram.com/d_degeaofficial/", "strWebsite": "", "strAgent": "", "strBirthLocation": "Madrid, Spain", "strKitColour": "Red", "strNumber": "1" } ] } ``` ``` -------------------------------- ### Video Youtube Highlights Source: https://www.thesportsdb.com/documentation/index Lists YouTube highlights associated with an event, filterable by date, league ID, or sport. ```APIDOC ## GET /eventshighlights.php ### Description See YouTube highlights for events on a particular date. You can filter by league ID or sport. ### Method GET ### Endpoint /api/v1/json/123/eventshighlights.php ### Parameters #### Query Parameters - **d** (Date) - Required - The date for which to retrieve highlights (YYYY-MM-DD). - **l** (Integer) - Optional - Filters by league ID. - **s** (String) - Optional - Filters by sport name. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07 https://www.thesportsdb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07&l=4684 https://www.thesportsdb.com/api/v1/json/123/eventshighlights.php?d=2024-07-07&s=motorsport ``` ### Response #### Success Response (200) - **Events** (Array) - A list of events with associated YouTube highlights. ``` -------------------------------- ### Schedule Day Source: https://www.thesportsdb.com/documentation/index Retrieves events for a specific date, with optional filters for sport and league. ```APIDOC ## GET /eventsday.php ### Description See the events on a specific day in the future, past or present. You can also add an optional filter for league ID or sport. ### Method GET ### Endpoint /api/v1/json/123/eventsday.php ### Parameters #### Query Parameters - **d** (Date) - Required - The date to retrieve events for (YYYY-MM-DD). - **s** (String) - Optional - Filters events by sport name. - **l** (String) - Optional - Filters events by league name. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/eventsday.php?d=2014-10-10 https://www.thesportsdb.com/api/v1/json/123/eventsday.php?d=2014-10-10&s=Baseball https://www.thesportsdb.com/api/v1/json/123/eventsday.php?d=2014-10-10&l=MLB ``` ### Response #### Success Response (200) - **Events** (Array) - A list of events occurring on the specified date, with optional filters applied. ``` -------------------------------- ### V2 Authentication Source: https://www.thesportsdb.com/documentation/index V2 API employs a more modern and secure authentication method by requiring the API key to be sent in the request header. ```APIDOC ## V2 Authentication v2 takes a more secure, modern approach to Authentication. When sending a request to the API base URL, you must include API key in the header using this attribute 'X-API-KEY'. ### Example Request Header: ``` X-API-KEY: YOUR_API_KEY_GOES_HERE ``` ``` -------------------------------- ### Schedule Team Next Events Source: https://www.thesportsdb.com/documentation/index Retrieve the next few upcoming events for a team using its ID. ```APIDOC ## GET /api/v1/json/:key/eventsnext.php ### Description See the next few upcoming events for a team using the Team ID. *free key only shows home event. ### Method GET ### Endpoint /api/v1/json/:key/eventsnext.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the team. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/eventsnext.php?id=133602 ``` ### Response #### Success Response (200) - **events** (Array) - An array of upcoming event objects for the specified team. #### Response Example ```json { "events": [ { "idEvent": "1041765", "strEvent": "Manchester United vs Brighton", "strEventAlternate": "Man Utd vs Brighton", "strFilename": "2024-01-30 Manchester United v Brighton And Hove Albion", "strSport": "Soccer", "idLeague": "4328", "strLeague": "English Premier League", "strSeason": "2023/2024", "strHomeTeam": "Manchester United", "strAwayTeam": "Brighton And Hove Albion", "intHomeScore": null, "intRound": "24", "intAwayScore": null, "dateEvent": "2024-01-30", " ``` -------------------------------- ### Lookup Event Details Source: https://www.thesportsdb.com/documentation/index Retrieve detailed information about a specific event using its unique ID. ```APIDOC ## GET /api/v1/json/:key/lookupevent.php ### Description Lookup a team's details using its ID. ### Method GET ### Endpoint /api/v1/json/:key/lookupevent.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the event to look up. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/lookupevent.php?id=441613 ``` ### Response #### Success Response (200) - **events** (Array) - An array of event objects containing event details. #### Response Example ```json { "events": [ { "idEvent": "441613", "strEvent": "Burnley vs Manchester Utd", "strFilename": "2009-09-20 Burnley v Manchester Utd", "strSport": "Soccer", "idLeague": "4328", "strLeague": "English Premier League", "idSoccerXML": "110793", "idAPIfootball": "441613", "resxido": "383559", "intHomeScore": "1", "intAwayScore": "0", "dateEvent": "2009-09-20", "strTime": "15:00:00", "strHomeTeam": "Burnley", "strAwayTeam": "Manchester Utd", "strHomeGoalDetails": "44' Robbie Blake", "strAwayGoalDetails": "", "intHomeShots": "7", "intAwayShots": "15", "strHomeYellowCards": "2", "strAwayYellowCards": "2", "strHomeRedCards": "0", "strAwayRedCards": "0", "strHomeLineupGoalkeeper": "Brian Jensen", "strHomeLineupDefense": "Caldwell, Carlisle, Bikey, Jordan", "strHomeLineupMidfield": "McCann, Thomas, McDonald, Eagles", "strHomeLineupForward": "Blake, Mears", "strHomeFormation": "4-4-2", "strAwayLineupGoalkeeper": "Ben Foster", "strAwayLineupDefense": "Neville, Evans, Ferdinand, Evra", "strAwayLineupMidfield": "Giggs, Scholes, Carrick, Park", "strAwayLineupForward": "Rooney, Berbatov", "strAwayFormation": "4-4-2", "intRound": "7", "strSeason": "2009/2010", "strTVStation": "Sky Sports 1", "strHomeBadge": "https://www.thesportsdb.com/images/media/team/badge/qjgpry1594772034.png", "strPreview": "", "strHomeReplaySource": "", "strHomeVideo": "", "strAwayReplaySource": "", "strAwayVideo": "", "strResult": " Burnley (1 - 0) Manchester Utd", "strTweetPosted": "0" } ] } ``` ``` -------------------------------- ### Schedule TV Source: https://www.thesportsdb.com/documentation/index Retrieves the TV schedule for a particular date, with optional filters for sport, country, channel, or channel ID. ```APIDOC ## GET /eventstv.php ### Description See the TV schedule for a particular date. You can filter by sport, country, channel, or channel ID. ### Method GET ### Endpoint /api/v1/json/123/eventstv.php ### Parameters #### Query Parameters - **d** (Date) - Required - The date for the TV schedule (YYYY-MM-DD). - **s** (String) - Optional - Filters by sport name. - **a** (String) - Optional - Filters by country name. - **c** (String) - Optional - Filters by channel name. - **id** (Integer) - Optional - Filters by channel ID. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/eventstv.php?d=2024-07-07 https://www.thesportsdb.com/api/v1/json/123/eventstv.php?d=2018-07-07&s=Fighting https://www.thesportsdb.com/api/v1/json/123/eventstv.php?d=2019-09-28&a=United_Kingdom&s=Cycling https://www.thesportsdb.com/api/v1/json/123/eventstv.php?c=Peacock_Premium https://www.thesportsdb.com/api/v1/json/123/eventstv.php?id=3834 ``` ### Response #### Success Response (200) - **Events** (Array) - A list of TV scheduled events matching the criteria. ``` -------------------------------- ### Lookup Player Results API Source: https://www.thesportsdb.com/documentation/index Lookup all results for a player using their unique ID. ```APIDOC ## GET /playerresults.php ### Description Lookup all results for a player using their ID. ### Method GET ### Endpoint /api/v1/json/123/playerresults.php ### Parameters #### Query Parameters - **id** (Integer) - Required - The ID of the player to look up. ### Request Example ``` https://www.thesportsdb.com/api/v1/json/123/playerresults.php?id=34160573 ``` ### Response #### Success Response (200) - **results** (Array) - Contains player result data. #### Response Example { "results": [ { "idEvent": "1000456", "strEvent": "Arsenal vs Tottenham", "dateEvent": "2016-11-06", "intHomeScore": "1", "intAwayScore": "1" } ] } ```