Skip to main content

MLS — MLS official web API (mlssoccer.com)

sportsdataverse.soccer.mls — 12 endpoints.

mls_club​

Single club detail (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/clubs/{club_id}

Valid URL: https://stats-api.mlssoccer.com/clubs/MLS-CLU-000001

API ParameterPythonPatternRequiredNullableDescription
club_idclub_idYclub_id path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
club_idStringSportec club id
club_nameStringFull club name
three_letter_codeString3-letter code
short_nameStringShort name
club_short_nameStringAlternate short name
club_three_letter_codeStringAlternate 3-letter code
cityStringHome city
countryStringCountry
long_nameStringLong/legal club name
foundedStringYear founded
stadium_idStringStadium id
stadium_nameStringStadium name
club_color_one_club_colorStringPrimary club colour: club colour name.
club_color_one_club_color_rgbStringPrimary club colour: club colour as an RGB hex string.
club_color_two_club_colorStringSecondary club colour: club colour name.
club_color_two_club_color_rgbStringSecondary club colour: club colour as an RGB hex string.
club_color_three_club_colorStringTertiary club colour: club colour name.
club_color_three_club_color_rgbStringTertiary club colour: club colour as an RGB hex string.
shirt_one_shirt_main_colorStringFirst-choice kit: main shirt colour name.
shirt_one_shirt_main_color_rgbStringFirst-choice kit: main shirt colour as an RGB hex string.
shirt_one_shirt_secondary_colorStringFirst-choice kit: secondary shirt colour name.
shirt_one_shirt_secondary_color_rgbStringFirst-choice kit: secondary shirt colour as an RGB hex string.
shirt_one_shirt_number_colorStringFirst-choice kit: shirt-number colour name.
shirt_one_shirt_number_color_rgbStringFirst-choice kit: shirt-number colour as an RGB hex string.
shirt_two_shirt_main_colorStringSecond-choice kit: main shirt colour name.
shirt_two_shirt_main_color_rgbStringSecond-choice kit: main shirt colour as an RGB hex string.
shirt_two_shirt_secondary_colorStringSecond-choice kit: secondary shirt colour name.
shirt_two_shirt_secondary_color_rgbStringSecond-choice kit: secondary shirt colour as an RGB hex string.
shirt_two_shirt_number_colorStringSecond-choice kit: shirt-number colour name.
shirt_two_shirt_number_color_rgbStringSecond-choice kit: shirt-number colour as an RGB hex string.
shirt_three_shirt_main_colorStringThird-choice kit: main shirt colour name.
shirt_three_shirt_main_color_rgbStringThird-choice kit: main shirt colour as an RGB hex string.
shirt_three_shirt_secondary_colorStringThird-choice kit: secondary shirt colour name.
shirt_three_shirt_secondary_color_rgbStringThird-choice kit: secondary shirt colour as an RGB hex string.
shirt_three_shirt_number_colorStringThird-choice kit: shirt-number colour name.
shirt_three_shirt_number_color_rgbStringThird-choice kit: shirt-number colour as an RGB hex string.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_club(club_id='MLS-CLU-000001')

mls_competition_seasons​

List seasons for a competition (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/competitions/{competition_id}/seasons

Valid URL: https://stats-api.mlssoccer.com/competitions/MLS-COM-000001/seasons

API ParameterPythonPatternRequiredNullableDescription
competition_idcompetition_idYcompetition_id path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
season_idStringSportec season id
seasonInt64Season year

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_competition_seasons(competition_id='MLS-COM-000001')

mls_competitions​

List competitions (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/competitions

Valid URL: https://stats-api.mlssoccer.com/competitions

API ParameterPythonPatternRequiredNullableDescription

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
competition_idStringSportec competition id
competition_nameStringCompetition display name
competition_name_frenchStringFrench competition name
countryStringCountry
competition_typeStringLeague or Tournament

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_competitions()

mls_content_season​

Season content entity by slug (dapi / Contentful).

Endpoint URL: GET https://dapi.mlssoccer.com/v2/content/en-us/seasons/{slug}

Valid URL: https://dapi.mlssoccer.com/v2/content/en-us/seasons/mls-regular-season-2026

API ParameterPythonPatternRequiredNullableDescription
slugslugYslug path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
typeStringType discriminator for the record.
_translation_idStringContentful translation-group id shared by every locale of this entry.
_entity_idStringContentful entity id for the content entry.
self_urlStringCanonical API URL of this content entry.
slugStringURL slug.
titleStringDisplay title.
tagsStringContent tags, JSON-encoded.
relationsStringRelated content entries, JSON-encoded.
created_byStringUser or service that created the content entry.
last_updated_byStringUser or service that last updated the content entry.
last_updated_dateStringTimestamp of the last content update (ISO 8601).
content_dateStringEditorial content date (ISO 8601).
featuredInt64Whether the entry is flagged as featured (1 = featured).
entity_codeStringContentful entity-type code.
_list_availabilityInt64Contentful flag controlling whether the entry appears in listings.
references_list_of_clubs_clinched_xStringContentful reference list: reference list of clubs that have clinched, list variant x.
references_list_of_clubs_clinched_eStringContentful reference list: reference list of clubs that have clinched, list variant e.
references_list_of_clubs_clinched_sStringContentful reference list: reference list of clubs that have clinched, list variant s.
references_list_of_clubs_clinched_yStringContentful reference list: reference list of clubs that have clinched, list variant y.
fields_opta_idStringSeason content field: parallel Opta integer id for the entity.
fields_sportec_idStringSeason content field: Sportec opaque id for the entity (Utf8 join key, never numeric).
fields_nameStringSeason content field: display name.
fields_competition_opta_idStringSeason content field: parallel Opta integer id of the competition.
fields_competition_sportec_idStringSeason content field: Sportec opaque id of the competition (Utf8 join key).
fields_standings_legendStringSeason content field: prose legend explaining the standings qualification bands.
fields_top_clubsInt64Season content field: number of clubs qualifying from the top of the table.
fields_top_clubs_legendStringSeason content field: prose legend explaining the top-clubs cut line.
fields_home_advantageInt64Season content field: points of home advantage applied by the playoff seeding rules.
fields_home_advantage_legendStringSeason content field: prose legend explaining the home-advantage rule.
fields_playoff_qualified_east_conferenceInt64Season content field: count of Eastern Conference clubs that have clinched a playoff berth.
fields_playoff_qualified_west_conferenceInt64Season content field: count of Western Conference clubs that have clinched a playoff berth.
fields_competition_sportec_id_overwriteBooleanSeason content field: competition: whether the season's Sportec id is manually overridden in the CMS.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_content_season(slug='mls-regular-season-2026')

mls_content_seasons​

Query season content entities (dapi / Contentful).

Endpoint URL: GET https://dapi.mlssoccer.com/v2/content/en-us/seasons

Valid URL: https://dapi.mlssoccer.com/v2/content/en-us/seasons

API ParameterPythonPatternRequiredNullableDescription
fields.competitionSportecIdcompetition_sportec_idYFilter by competition Sportec id (indexed field)
fields.sportecIdsportec_idYFilter by season Sportec id (indexed field)

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
typeStringType discriminator for the record.
_translation_idStringContentful translation-group id shared by every locale of this entry.
_entity_idStringContentful entity id for the content entry.
self_urlStringCanonical API URL of this content entry.
slugStringURL slug.
titleStringDisplay title.
tagsStringContent tags, JSON-encoded.
created_byStringUser or service that created the content entry.
last_updated_byStringUser or service that last updated the content entry.
last_updated_dateStringTimestamp of the last content update (ISO 8601).
content_dateStringEditorial content date (ISO 8601).
featuredInt64Whether the entry is flagged as featured (1 = featured).
entity_codeStringContentful entity-type code.
fields_opta_idStringSeason content field: parallel Opta integer id for the entity.
fields_sportec_idStringSeason content field: Sportec opaque id for the entity (Utf8 join key, never numeric).
fields_nameStringSeason content field: display name.
fields_competition_opta_idStringSeason content field: parallel Opta integer id of the competition.
fields_competition_sportec_idStringSeason content field: Sportec opaque id of the competition (Utf8 join key).
fields_standings_legendStringSeason content field: prose legend explaining the standings qualification bands.
fields_top_clubsInt64Season content field: number of clubs qualifying from the top of the table.
fields_top_clubs_legendStringSeason content field: prose legend explaining the top-clubs cut line.
fields_home_advantageInt64Season content field: points of home advantage applied by the playoff seeding rules.
fields_home_advantage_legendStringSeason content field: prose legend explaining the home-advantage rule.
fields_playoff_qualified_east_conferenceInt64Season content field: count of Eastern Conference clubs that have clinched a playoff berth.
fields_playoff_qualified_west_conferenceInt64Season content field: count of Western Conference clubs that have clinched a playoff berth.
fields_competition_sportec_id_overwriteBooleanSeason content field: competition: whether the season's Sportec id is manually overridden in the CMS.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_content_seasons()

mls_match​

Single match detail incl. lineups + referees (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/matches/{match_id}

Valid URL: https://stats-api.mlssoccer.com/matches/MLS-MAT-0009H8

API ParameterPythonPatternRequiredNullableDescription
match_idmatch_idYmatch_id path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
competition_idStringSportec competition id
competition_nameStringCompetition display name
away_team_goalsInt64Away goals
home_team_goalsInt64Home goals
kickoff_timeStringActual kickoff timestamp (ISO 8601)
match_dayInt64Matchday / round number
match_idStringSportec match id (MLS-MAT-*)
match_titleStringHome:Away title, e.g. CF Montréal:Toronto FC
planned_kickoff_timeStringScheduled kickoff timestamp (ISO 8601)
resultStringFinal score string, e.g. 0:0
seasonInt64Season year
season_idStringSportec season id
competition_typeStringLeague or Tournament
section_nameStringSeason section / phase
competition_labelStringShort competition label
series_typeStringSeries type (e.g. regular)
total_time_first_halfInt64First-half elapsed seconds
total_time_second_halfInt64Second-half elapsed seconds
playing_time_first_halfInt64First-half playing seconds
playing_time_second_halfInt64Second-half playing seconds
total_time_first_half_extraInt64First-half stoppage seconds
total_time_second_half_extraInt64Second-half stoppage seconds
total_time_penaltyInt64Penalty-shootout total seconds
playing_time_penaltyInt64Penalty-shootout playing seconds
other_informationStringFree-form notes
match_typeStringMatch classification
match_scheduledBooleanWhether kickoff is scheduled
date_qualityStringConfidence of the match date
end_dateStringMatch end date
sub_leagueStringSub-league grouping
groupStringGroup name (tournaments)
competition_name_frenchStringFrench competition name
match_statusStringStatus (e.g. Live, FullTime)
minute_of_playStringCurrent minute (live)

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_match(match_id='MLS-MAT-0009H8')

mls_season_matches​

List matches in a season, date-windowed (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/matches/seasons/{season_id}

Valid URL: https://stats-api.mlssoccer.com/matches/seasons/MLS-SEA-0001KA

API ParameterPythonPatternRequiredNullableDescription
season_idseason_idYseason_id path parameter.
match_date[gte]match_date_gteYWindow start date (YYYY-MM-DD)
match_date[lte]match_date_lteYWindow end date (YYYY-MM-DD)
competition_idcompetition_idYFilter by competition id
per_pageper_pageYPage size
sortsortYSort spec, e.g. planned_kickoff_time:asc,home_team_name:asc
series_nameseries_nameYFilter by series/round name

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
competition_idStringSportec competition id
competition_nameStringCompetition display name
competition_typeStringLeague or Tournament
end_dateStringMatch end date
away_team_idStringAway Sportec club id
away_team_nameStringAway club name
home_team_idStringHome Sportec club id
home_team_nameStringHome club name
home_team_short_nameStringHome short name
home_team_three_letter_codeStringHome 3-letter code
away_team_short_nameStringAway short name
away_team_three_letter_codeStringAway 3-letter code
match_scheduledBooleanWhether kickoff is scheduled
match_dayInt64Matchday / round number
match_day_idStringSportec matchday id
match_idStringSportec match id (MLS-MAT-*)
match_typeStringMatch classification
planned_kickoff_timeStringScheduled kickoff timestamp (ISO 8601)
seasonInt64Season year
season_idStringSportec season id
stadium_idStringStadium id
stadium_nameStringStadium name
neutral_venueBooleanNeutral-venue flag
start_dateStringMatch start date
sub_leagueStringSub-league grouping
groupStringGroup name (tournaments)
date_qualityStringConfidence of the match date
official_informationStringOfficiating notes
match_date_time_statusStringKickoff time status
section_nameStringSeason section / phase
competition_labelStringShort competition label
series_typeStringSeries type (e.g. regular)
competition_name_frenchStringFrench competition name
resultStringFinal score string, e.g. 0:0
away_team_goalsInt64Away goals
home_team_goalsInt64Home goals
match_statusStringStatus (e.g. Live, FullTime)
minute_of_playStringCurrent minute (live)
stadium_cityStringStadium city
stadium_countryStringStadium country
bracket_structure_idStringIdentifier of the playoff bracket structure.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_season_matches(season_id='MLS-SEA-0001KA')

mls_sportapi_club_players​

Club roster with player Sportec ids (sportapi).

Endpoint URL: GET https://sportapi.mlssoccer.com/api/players/byClub/{club_id}

Valid URL: https://sportapi.mlssoccer.com/api/players/byClub/MLS-CLU-000001

API ParameterPythonPatternRequiredNullableDescription
club_idclub_idYclub_id path parameter.
culturecultureYLocale, e.g. en-us

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
opta_idStringParallel Opta integer id for the entity.
full_nameStringFull name
first_nameStringFirst name
last_nameStringLast name
known_nameStringKnown / display name
on_loanBooleanOn-loan flag
club_opta_idStringClub Opta id
club_sportec_idStringClub Sportec id
sportec_idStringSportec opaque id for the entity (Utf8 join key, never numeric).
heightStringHeight
weightStringWeight
positionStringTable position/rank
roster_categoryStringRoster category
player_categoriesStringRoster category tags
jersey_numberStringJersey number
player_status_listStringStatus tags (e.g. Loaned Out)
date_of_birthStringBirth date
player_slugStringURL slug
thumbnail_slugStringPlayer thumbnail image: URL slug.
thumbnail_self_urlStringPlayer thumbnail image: canonical API URL of this content entry.
thumbnail_titleStringPlayer thumbnail image: display title.
thumbnail_template_urlStringPlayer thumbnail image: templated image URL with substitutable size tokens.
thumbnail_thumbnail_urlStringPlayer thumbnail image: URL of the rendered thumbnail image.
thumbnail_formatStringPlayer thumbnail image: image format of the asset.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_sportapi_club_players(club_id='MLS-CLU-000001')

mls_sportapi_clubs_by_sportec_ids​

Batch club detail by Sportec ids (sportapi).

Endpoint URL: GET https://sportapi.mlssoccer.com/api/clubs/bySportecIds/{ids}

Valid URL: https://sportapi.mlssoccer.com/api/clubs/bySportecIds/MLS-MAT-0009H8

API ParameterPythonPatternRequiredNullableDescription
idsidsYids path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
opta_idStringParallel Opta integer id for the entity.
sportec_idStringSportec opaque id for the entity (Utf8 join key, never numeric).
full_nameStringFull name
slugStringURL slug.
short_nameStringShort name
abbreviationString
background_colorStringBrand background colour (hex).
logo_bw_slugStringAsset slug for the black-and-white logo.
logo_color_slugStringAsset slug for the full-colour logo.
logo_color_urlStringURL of the full-colour logo asset.
crest_color_slugStringAsset slug for the full-colour club crest.
ecal_widget_idStringIdentifier of the eCal calendar-subscription widget.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_sportapi_clubs_by_sportec_ids(ids='MLS-MAT-0009H8')

mls_sportapi_match​

Single match detail (sportapi / .NET).

Endpoint URL: GET https://sportapi.mlssoccer.com/api/matches/{match_id}

Valid URL: https://sportapi.mlssoccer.com/api/matches/MLS-MAT-0009H8

API ParameterPythonPatternRequiredNullableDescription
match_idmatch_idYmatch_id path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
opta_idStringParallel Opta integer id for the entity.
sportec_idStringSportec opaque id for the entity (Utf8 join key, never numeric).
slugStringURL slug.
league_match_titleStringHome:Away match title as rendered in league listings.
broadcastersStringBroadcast listings for the match, JSON-encoded.
match_dateStringScheduled kickoff timestamp (ISO 8601).
tagsStringContent tags, JSON-encoded.
home_club_broadcastersStringHome club: club-specific broadcast listings, JSON-encoded.
away_club_broadcastersStringAway club: club-specific broadcast listings, JSON-encoded.
club_broadcastersStringClub-specific broadcast listings, JSON-encoded.
is_time_tbdBooleanWhether the kickoff time is still to be confirmed.
mgm_idStringMGM sportsbook partner identifier.
apple_stream_urlStringApple broadcast: Apple TV stream URL for the match.
apple_subscription_tierStringApple broadcast: Apple subscription tier required to watch.
apple_advertisement_categoryStringApple broadcast: Apple advertising category for the stream.
round_nameStringName of the round or series this match belongs to.
competition_phaseStringCompetition: competition phase of the match (regular season, playoffs, ...).
home_club_rankStringHome club: club's standings rank at the time of the request.
away_club_rankStringAway club: club's standings rank at the time of the request.
round_numberInt64
round_groupStringGroup label within the round (tournaments).
match_dayStringMatchday / round number
calendar_urlStringCalendar (.ics) subscription URL for the match.
delayed_matchBooleanWhether the match is flagged as delayed.
priority_match_date_toStringPriority-match window: end of the display window (ISO 8601).
priority_match_sponsorStringPriority-match window: sponsor name attached to the priority match.
home_opta_idStringHome club: parallel Opta integer id for the entity.
home_sportec_idStringHome club: Sportec opaque id for the entity (Utf8 join key, never numeric).
home_full_nameStringHome club: full name
home_slugStringHome club: URL slug.
home_short_nameStringHome club: short name
home_abbreviationString
home_background_colorStringHome club: brand background colour (hex).
home_logo_bw_slugStringHome club: asset slug for the black-and-white logo.
home_logo_color_slugStringHome club: asset slug for the full-colour logo.
home_logo_color_urlStringHome club: URL of the full-colour logo asset.
home_crest_color_slugStringHome club: asset slug for the full-colour club crest.
home_ecal_widget_idStringHome club: identifier of the eCal calendar-subscription widget.
away_opta_idStringAway club: parallel Opta integer id for the entity.
away_sportec_idStringAway club: Sportec opaque id for the entity (Utf8 join key, never numeric).
away_full_nameStringAway club: full name
away_slugStringAway club: URL slug.
away_short_nameStringAway club: short name
away_abbreviationString
away_background_colorStringAway club: brand background colour (hex).
away_logo_bw_slugStringAway club: asset slug for the black-and-white logo.
away_logo_color_slugStringAway club: asset slug for the full-colour logo.
away_logo_color_urlStringAway club: URL of the full-colour logo asset.
away_crest_color_slugStringAway club: asset slug for the full-colour club crest.
away_ecal_widget_idStringAway club: identifier of the eCal calendar-subscription widget.
venue_venue_sportec_idStringVenue: Sportec opaque id of the venue (Utf8 join key).
venue_background_image_slugStringVenue: asset slug for the background image.
venue_nameStringVenue: display name.
venue_cityStringVenue: home city
season_slugStringSeason: URL slug.
season_opta_idStringSeason: parallel Opta integer id for the entity.
season_sportec_idStringSeason: Sportec opaque id for the entity (Utf8 join key, never numeric).
season_competition_opta_idStringSeason: parallel Opta integer id of the competition.
season_nameStringSeason: display name.
competition_opta_idStringParallel Opta integer id of the competition.
competition_sportec_idStringSportec opaque id of the competition (Utf8 join key).
competition_nameStringCompetition display name
competition_widget_idStringCompetition: identifier of the embedded provider widget.
competition_slugStringCompetition: URL slug.
competition_short_nameStringCompetition: short name
competition_match_typeStringCompetition: Match classification
competition_logo_light_slugStringCompetition light-theme logo: URL slug.
competition_logo_dark_slugStringCompetition dark-theme logo: URL slug.
competition_block_header_nameStringCompetition: header label used for this competition on the site.
competition_mgm_idStringCompetition: MGM sportsbook partner identifier.
competition_nextgen_ecal_match_hub_displayBooleanCompetition: whether the match hub shows the eCal subscribe control.
competition_player_headshot_thumbnail_fieldStringCompetition: content field the site reads player headshots from.
league_promo_image_asset_urlStringLeague promo image: URL of the image asset.
first_party_tickets_display_textStringMLS-operated ticketing link: button label for the ticketing link.
first_party_tickets_accessible_textStringMLS-operated ticketing link: accessible (screen-reader) label for the ticketing link.
first_party_tickets_urlStringMLS-operated ticketing link: link URL.
first_party_tickets_open_in_new_tabBooleanMLS-operated ticketing link: whether the link opens in a new tab.
first_party_tickets_is_visibleBooleanMLS-operated ticketing link: whether the link is shown.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_sportapi_match(match_id='MLS-MAT-0009H8')

mls_sportapi_matches_by_sportec_ids​

Batch match detail by Sportec ids (sportapi).

Endpoint URL: GET https://sportapi.mlssoccer.com/api/matches/bySportecIds/{ids}

Valid URL: https://sportapi.mlssoccer.com/api/matches/bySportecIds/MLS-MAT-0009H8

API ParameterPythonPatternRequiredNullableDescription
idsidsYids path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
opta_idStringParallel Opta integer id for the entity.
sportec_idStringSportec opaque id for the entity (Utf8 join key, never numeric).
slugStringURL slug.
league_match_titleStringHome:Away match title as rendered in league listings.
broadcastersStringBroadcast listings for the match, JSON-encoded.
match_dateStringScheduled kickoff timestamp (ISO 8601).
tagsStringContent tags, JSON-encoded.
home_club_broadcastersStringHome club: club-specific broadcast listings, JSON-encoded.
away_club_broadcastersStringAway club: club-specific broadcast listings, JSON-encoded.
club_broadcastersStringClub-specific broadcast listings, JSON-encoded.
is_time_tbdBooleanWhether the kickoff time is still to be confirmed.
mgm_idStringMGM sportsbook partner identifier.
apple_stream_urlStringApple broadcast: Apple TV stream URL for the match.
apple_subscription_tierStringApple broadcast: Apple subscription tier required to watch.
apple_advertisement_categoryStringApple broadcast: Apple advertising category for the stream.
round_nameStringName of the round or series this match belongs to.
competition_phaseStringCompetition: competition phase of the match (regular season, playoffs, ...).
home_club_rankStringHome club: club's standings rank at the time of the request.
away_club_rankStringAway club: club's standings rank at the time of the request.
round_numberInt64
round_groupStringGroup label within the round (tournaments).
match_dayStringMatchday / round number
calendar_urlStringCalendar (.ics) subscription URL for the match.
delayed_matchBooleanWhether the match is flagged as delayed.
priority_match_date_toStringPriority-match window: end of the display window (ISO 8601).
priority_match_sponsorStringPriority-match window: sponsor name attached to the priority match.
home_opta_idStringHome club: parallel Opta integer id for the entity.
home_sportec_idStringHome club: Sportec opaque id for the entity (Utf8 join key, never numeric).
home_full_nameStringHome club: full name
home_slugStringHome club: URL slug.
home_short_nameStringHome club: short name
home_abbreviationString
home_background_colorStringHome club: brand background colour (hex).
home_logo_bw_slugStringHome club: asset slug for the black-and-white logo.
home_logo_color_slugStringHome club: asset slug for the full-colour logo.
home_logo_color_urlStringHome club: URL of the full-colour logo asset.
home_crest_color_slugStringHome club: asset slug for the full-colour club crest.
away_opta_idStringAway club: parallel Opta integer id for the entity.
away_sportec_idStringAway club: Sportec opaque id for the entity (Utf8 join key, never numeric).
away_full_nameStringAway club: full name
away_slugStringAway club: URL slug.
away_short_nameStringAway club: short name
away_abbreviationString
away_background_colorStringAway club: brand background colour (hex).
away_logo_bw_slugStringAway club: asset slug for the black-and-white logo.
away_logo_color_slugStringAway club: asset slug for the full-colour logo.
away_logo_color_urlStringAway club: URL of the full-colour logo asset.
away_crest_color_slugStringAway club: asset slug for the full-colour club crest.
venue_venue_sportec_idStringVenue: Sportec opaque id of the venue (Utf8 join key).
venue_nameStringVenue: display name.
venue_cityStringVenue: home city
season_slugStringSeason: URL slug.
season_opta_idStringSeason: parallel Opta integer id for the entity.
season_sportec_idStringSeason: Sportec opaque id for the entity (Utf8 join key, never numeric).
season_competition_opta_idStringSeason: parallel Opta integer id of the competition.
season_nameStringSeason: display name.
competition_opta_idStringParallel Opta integer id of the competition.
competition_sportec_idStringSportec opaque id of the competition (Utf8 join key).
competition_nameStringCompetition display name
competition_widget_idStringCompetition: identifier of the embedded provider widget.
competition_slugStringCompetition: URL slug.
competition_short_nameStringCompetition: short name
competition_match_typeStringCompetition: Match classification
competition_logo_light_slugStringCompetition light-theme logo: URL slug.
competition_logo_dark_slugStringCompetition dark-theme logo: URL slug.
competition_block_header_nameStringCompetition: header label used for this competition on the site.
competition_mgm_idStringCompetition: MGM sportsbook partner identifier.
competition_nextgen_ecal_match_hub_displayBooleanCompetition: whether the match hub shows the eCal subscribe control.
competition_player_headshot_thumbnail_fieldStringCompetition: content field the site reads player headshots from.
league_promo_image_asset_urlStringLeague promo image: URL of the image asset.
third_party_tickets_urlStringThird-party ticketing link: link URL.
third_party_tickets_open_in_new_tabBooleanThird-party ticketing link: whether the link opens in a new tab.
third_party_tickets_is_visibleBooleanThird-party ticketing link: whether the link is shown.
priority_match_date_fromStringPriority-match window: start of the display window (ISO 8601).
home_ecal_widget_idStringHome club: identifier of the eCal calendar-subscription widget.
away_ecal_widget_idStringAway club: identifier of the eCal calendar-subscription widget.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_sportapi_matches_by_sportec_ids(ids='MLS-MAT-0009H8')

mls_standings​

Standings table for a competition season (stats-api).

Endpoint URL: GET https://stats-api.mlssoccer.com/competitions/{competition_id}/seasons/{season_id}/standings

Valid URL: https://stats-api.mlssoccer.com/competitions/MLS-COM-000001/seasons/MLS-SEA-0001KA/standings

API ParameterPythonPatternRequiredNullableDescription
competition_idcompetition_idYcompetition_id path parameter.
season_idseason_idYseason_id path parameter.
categorycategoryYStandings grouping: conference | overall
typestandings_typeYhome | away split (optional)
is_liveis_liveYInclude live in-progress results

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
competition_idStringSportec competition id
season_idStringSportec season id
groupStringGroup name (tournaments)
categoryString
typeStringType discriminator for the record.
positionInt64Table position/rank
clubStringClub full name
club_idStringSportec club id
teamStringTeam name
team_idStringSportec club id
team_short_nameStringShort club name
team_three_letter_codeString3-letter club code
games_playedInt64Matches played
winsInt64Wins
drawsInt64Draws
lossesInt64Losses
goals_scoredInt64Goals for
goals_againstInt64Goals against
goals_differenceInt64Goal differential
pointsInt64Points
qualificationStringPlayoff/qualification marker
tendencyStringMovement vs prior matchday
points_per_gameFloat64Points per game
goals_scored_per_gameFloat64Goals-for per game
goals_against_per_gameFloat64Goals-against per game
goals_difference_per_gameFloat64Goal-diff per game

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
sportsdataverse.errors.NoESPNDataErrorThe host answered 404 -- the requested resource does not exist. The MLS host returned 404 (unknown id, or an unplayed match on /matches/{matchId}). On the season-addressable stats-api endpoints (season_matches, standings, competition_seasons) a season before 2024 has no addressable id -- the stats-api serves 2024+ only.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mls_standings(competition_id='MLS-COM-000001', season_id='MLS-SEA-0001KA')