WorldReferee APIworldreferee.com ↗
Access upcoming football match referee appointments from WorldReferee.com. Get home/away teams, competition, match date, and assigned official via one API endpoint.
What is the WorldReferee API?
The WorldReferee.com API exposes 1 endpoint, get_upcoming_appointments, that returns all upcoming football matches with confirmed or pending referee assignments. Each match object includes 5 fields — home team, away team, referee name, competition, and date — giving you a structured view of official appointments across multiple competitions before match day.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/3b98e6fb-23e3-4498-bf1a-1f9c48148b04/get_upcoming_appointments' \ -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 worldreferee-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.
"""Walkthrough: WorldReferee SDK — list upcoming football referee appointments."""
from parse_apis.worldreferee_com_api import WorldReferee, UpstreamError
client = WorldReferee()
# Fetch upcoming matches, capped at 10 items
try:
for match in client.appointments.list(limit=10):
print(f"{match.home_team} vs {match.away_team} | {match.competition} | {match.date} | Referee: {match.referee}")
except UpstreamError as e:
# Source site may be temporarily unavailable
print(f"Upstream error: {e}")
# Use .first() to grab a single upcoming appointment
next_match = client.appointments.list(limit=1).first()
if next_match is not None:
print(f"\nNext match: {next_match.home_team} vs {next_match.away_team}")
print(f" Competition: {next_match.competition}")
print(f" Date: {next_match.date}")
print(f" Referee: {next_match.referee}")
print("\nexercised: appointments.list")
Returns all upcoming football matches with their referee appointments listed on WorldReferee.com. Each match includes home team, away team, competition name, match date, and assigned referee (or 'TBA' if not yet announced). Results are grouped by competition and date on the source page; this endpoint flattens them into a single array. Typically returns 40-80 matches spanning the next 1-2 weeks across multiple leagues (La Liga, Bundesliga, Ligue 1, Serie A, Premier League, etc.). No pagination — one call returns all listed matches.
No input parameters required.
{
"type": "object",
"fields": {
"total": "integer count of matches returned",
"matches": "array of match objects with home_team, away_team, referee, competition, and date"
},
"sample": {
"data": {
"total": 60,
"matches": [
{
"date": "Friday 28 August 2026",
"referee": "TBA",
"away_team": "Elche CF",
"home_team": "Real Racing Club de Santander",
"competition": "La Liga"
},
{
"date": "Friday 28 August 2026",
"referee": "TBA",
"away_team": "VfB Stuttgart",
"home_team": "FC Bayern München",
"competition": "Bundesliga"
}
]
},
"status": "success"
}
}About the WorldReferee API
What the API Returns
The get_upcoming_appointments endpoint returns a flat list of upcoming football matches alongside their assigned match officials. The response envelope contains a total integer showing how many matches were found, and a matches array where every entry carries home_team, away_team, referee, competition, and date. When a referee has not yet been confirmed by the governing body, the referee field returns the string 'TBA' rather than a name.
Coverage and Structure
Matches span multiple competitions — domestic leagues, cups, and international fixtures — reflecting the breadth of appointments listed on WorldReferee.com. Data is organized by competition and date at the source, and the response preserves that grouping implicitly through the competition and date fields on each match object. There are no required input parameters; a single call retrieves all available upcoming appointments in one response.
Practical Considerations
Because referee assignments are announced at different times by different football bodies, any given call may return a mix of confirmed names and 'TBA' entries. Polling the endpoint regularly in the days leading up to a match round is the practical way to catch newly announced officials. The endpoint returns every match currently listed on the upcoming page — there is no built-in pagination or competition filter, so any filtering by competition or date range needs to be applied client-side after retrieving the full result set.
The WorldReferee API is a managed, monitored endpoint for worldreferee.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when worldreferee.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 worldreferee.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?+
- Monitor referee assignments across multiple leagues before a match weekend to guide betting or editorial decisions.
- Build automated alerts that notify analysts when a specific referee's name appears in the
refereefield. - Compile historical referee workload data by logging repeated calls and tracking how often each official appears.
- Cross-reference
competitionandrefereefields to identify which officials are assigned to high-profile fixtures. - Feed a dashboard that flags all matches still showing
'TBA'so coverage teams know which appointments are pending. - Aggregate upcoming fixture lists with referee data for fantasy sports platforms that weight official tendencies.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does WorldReferee.com have an official developer API?+
What does the `get_upcoming_appointments` endpoint return for unconfirmed referees?+
referee field in the match object returns the string 'TBA'. All other fields — home_team, away_team, competition, and date — are still populated. You can filter client-side on referee !== 'TBA' to isolate only confirmed appointments.Can I filter results by competition or date range before they are returned?+
get_upcoming_appointments endpoint takes no input parameters, so filtering is not available server-side. The full set of upcoming matches is returned in one call, and any narrowing by competition or date must be done in your own code after receiving the response. You can fork this API on Parse and revise it to add query parameters that filter before returning results.Does the API include past match results or historical referee statistics?+
How fresh is the data, and how often should I call the endpoint?+
'TBA' entries resolve to named officials.