MLS Soccer APImlssoccer.com ↗
Fetch MLS match schedules, live scores, and detailed game info via the mlssoccer.com API. Covers Regular Season, MLS NEXT Pro, US Open Cup, and CONCACAF Champions Cup.
What is the MLS Soccer API?
The mlssoccer.com API provides access to MLS match data across 2 endpoints, returning live scores, upcoming fixtures, and completed results for all major competitions. The get_matches endpoint retrieves matches within a date range filtered by competition, while get_match_details returns per-match information including team logos, broadcaster details, venue, and streaming URLs for a specific match ID.
curl -X GET 'https://api.parse.bot/scraper/fac056a7-b2b6-4a9f-8c3a-aeea37e99963/get_matches?date_to=2026-07-17&date_from=2026-04-12&competition=mls-next-pro' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace mlssoccer-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""MLS Soccer: fetch match schedules, filter by competition, and drill into match details."""
from parse_apis.mls_soccer_schedule_scores_api import MLS, Competition, MatchNotFound
client = MLS()
# List upcoming MLS Regular Season matches (capped to 5 total items)
for match in client.matchsummaries.list(competition=Competition.MLS, limit=5):
print(match.home_team.name, "vs", match.away_team.name, "|", match.score, "|", match.kickoff_time)
# Drill into the first match's full details via the summary→detail navigation
summary = client.matchsummaries.list(limit=1).first()
if summary:
detail = summary.details()
print(detail.home_team.name, detail.home_team.abbreviation, detail.home_team.logo_url)
print(detail.venue.name, detail.venue.city)
print(detail.competition.name, detail.season.name)
for bc in detail.broadcasters:
print(bc.name, bc.type, bc.streaming_url)
# Fetch a match directly by ID and handle not-found errors
try:
match = client.matches.get(match_id="MLS-MAT-0009FO")
print(match.match_id, match.slug, match.match_date)
except MatchNotFound as exc:
print(f"Match not found: {exc.match_id}")
print("exercised: matchsummaries.list / summary.details / matches.get / MatchNotFound error handling")
Get MLS matches for a date range. Returns live scores, upcoming matches with start times, and completed results. Includes match status (scheduled, live, finalWhistle), team names, scores, kickoff times, and venue info. Results are sorted by kickoff time. When competition is omitted or unrecognized, returns all competitions without filtering.
| Param | Type | Description |
|---|---|---|
| date_to | string | End date in YYYY-MM-DD format. Defaults to 6 days from current UTC date. |
| date_from | string | Start date in YYYY-MM-DD format. Defaults to yesterday relative to current UTC date. |
| competition | string | Filter by competition. Returns all competitions if omitted or unrecognized. |
{
"type": "object",
"fields": {
"date_to": "string - end date used for the query",
"matches": "array of MatchSummary objects",
"date_from": "string - start date used for the query",
"total_matches": "integer - number of matches returned"
}
}About the MLS Soccer API
Match Schedules and Live Scores
The get_matches endpoint accepts optional date_from and date_to parameters in YYYY-MM-DD format, defaulting to yesterday through six days ahead. Each match object includes match_id, match_status (one of scheduled, live, or finalWhistle), competition, competition_label, match_type, home and away team names with short names and abbreviations, scores, and kickoff times. Results are sorted by kickoff time. The optional competition filter accepts values such as mls-regular, mls-next-pro, us-open-cup, and next-pro, letting you narrow the result set to a specific league or cup.
Detailed Match Information
The get_match_details endpoint takes a single required match_id (e.g. MLS-MAT-0009FO, obtained from get_matches) and returns a richer object. Fields include home_team and away_team objects with name, short_name, abbreviation, id, slug, and logo_url; a venue object with name and city; match_date in ISO 8601 UTC; match_day; round_name for cup or playoff stages; and a competition object with name, short_name, and slug. The endpoint also surfaces broadcaster and streaming URL data not available from the schedule endpoint. If the provided match_id is not found, the endpoint returns a stale_input status rather than an error.
Competition Coverage
The API covers four competitions accessible via the competition filter: MLS Regular Season (mls or mls-regular), MLS NEXT Pro (mls-next-pro or next-pro), US Open Cup (us-open-cup), and CONCACAF Champions Cup. This maps directly to the competitions MLS publishes through mlssoccer.com. The competition_label field on each match object carries the human-readable competition name for display purposes.
The MLS Soccer API is a managed, monitored endpoint for mlssoccer.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when mlssoccer.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official mlssoccer.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a live MLS scoreboard widget using
match_statusand current scores fromget_matches - Build a fixture calendar for a specific club by filtering
get_matchesresults by team name over a date range - Show broadcaster and streaming links for an upcoming match using
get_match_details - Track MLS NEXT Pro results by filtering
get_matcheswith themls-next-procompetition value - Render team crests in a match preview using
logo_urlfromget_match_detailshome and away team objects - Surface venue and city information for travel or event planning using the
venueobject inget_match_details - Identify cup round and stage context (e.g. semifinals) via the
round_namefield inget_match_details
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does MLS Soccer have an official developer API?+
What does `match_status` return and what values should I expect?+
match_status field in get_matches returns one of three string values: scheduled for fixtures that have not yet kicked off, live for matches currently in progress, and finalWhistle for completed matches. This field is the primary signal for distinguishing upcoming, in-progress, and finished games.Does the API return player stats, lineups, or goal scorers?+
How far ahead or behind can I query with `get_matches`?+
date_from and date_to parameters accept any YYYY-MM-DD value. The defaults cover yesterday through six days ahead, but you can specify arbitrary past or future dates to query historical results or fixtures further out, as long as the data exists for that range on mlssoccer.com.