> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/referees.md). # Referees #### What does the include do? The `referees` include returns the match officials assigned to a fixture. Unlike the `coaches` include, this is a **lean linking object**, it does not embed the official's name or biographical data directly. You get IDs and a type, and need a separate lookup to get the person's details. #### Why use referees? * **Match centre displays**: Show who officiated a fixture * **Referee performance tracking**: Combine with the standalone Referee endpoint's statistics to analyse card counts, penalties given, etc. per official * **Data consistency checks**: Confirm which officials were assigned before publishing match reports #### Requesting referees ```http https://api.sportmonks.com/v3/football/fixtures/{fixture_id} ?api_token=YOUR_TOKEN&include=referees ``` #### Response structure ```json { "data": { "id": 18535517, "name": "Celtic vs Rangers", "referees": [ { "id": 2123470, "fixture_id": 18535517, "referee_id": 14468, "type_id": 6 } ] } } ``` #### Field descriptions | Field | Type | Description | | ------------ | ------- | --------------------------------------------------------------------- | | `id` | integer | Unique identifier for this referee assignment record | | `fixture_id` | integer | The fixture this assignment belongs to | | `referee_id` | integer | Links to the full referee record, see below to resolve this to a name | | `type_id` | integer | Which officiating role this person held, see table below | #### Referee type values Confirmed via `/core/types`: | `type_id` | Role | | --------- | ------------- | | 6 | Referee | | 7 | 1st Assistant | | 8 | 2nd Assistant | | 9 | 4th Official | | 10 | VAR | {% hint style="warning" %} **Not all roles are guaranteed to appear, even in VAR-using leagues.** Live testing on a Scottish Premiership fixture from a season when VAR was active returned **only one entry** (`type_id: 6`, the main Referee), with no 4th Official or VAR entry present. Don't assume a fixture will include all five roles, or that a missing VAR entry means VAR wasn't used, coverage depends on what data was tracked for that specific match. {% endhint %} #### Getting the referee's name The fixture-level `referees` include only gives you `referee_id`. To resolve this to a name and profile, make a separate request to the standalone Referee endpoint: ```http https://api.sportmonks.com/v3/football/referees/{referee_id} ?api_token=YOUR_TOKEN ``` ```json { "data": { "id": 14468, "sport_id": 1, "country_id": 1161, "city_id": null, "common_name": "J. Beaton", "firstname": "John", "lastname": "Beaton", "name": "John Beaton", "display_name": "J. Beaton", "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png", "height": null, "weight": null, "date_of_birth": null, "gender": null } } ``` #### Code examples {% tabs %} {% tab title="JavaScript" %} ```javascript const API_TOKEN = "YOUR_TOKEN"; const FIXTURE_ID = 18535517; async function getFixtureReferee() { const fixtureUrl = `https://api.sportmonks.com/v3/football/fixtures/${FIXTURE_ID}`; const fixtureResponse = await fetch(`${fixtureUrl}?api_token=${API_TOKEN}&include=referees`); const fixture = (await fixtureResponse.json()).data; const mainReferee = fixture.referees.find(r => r.type_id === 6); if (!mainReferee) { console.log("No main referee assigned for this fixture."); return; } const refUrl = `https://api.sportmonks.com/v3/football/referees/${mainReferee.referee_id}`; const refResponse = await fetch(`${refUrl}?api_token=${API_TOKEN}`); const referee = (await refResponse.json()).data; console.log(`Referee: ${referee.display_name}`); } getFixtureReferee(); ``` {% endtab %} {% tab title="Python" %} ```python import requests API_TOKEN = "YOUR_TOKEN" FIXTURE_ID = 18535517 fixture_url = f"https://api.sportmonks.com/v3/football/fixtures/{FIXTURE_ID}" fixture = requests.get(fixture_url, params={ "api_token": API_TOKEN, "include": "referees" }).json()['data'] main_referee = next((r for r in fixture['referees'] if r['type_id'] == 6), None) if main_referee: ref_url = f"https://api.sportmonks.com/v3/football/referees/{main_referee['referee_id']}" referee = requests.get(ref_url, params={"api_token": API_TOKEN}).json()['data'] print(f"Referee: {referee['display_name']}") else: print("No main referee assigned for this fixture.") ``` {% endtab %} {% tab title="PHP" %} ```php $apiToken, "include" => "referees"]); $fixture = json_decode(file_get_contents("{$fixtureUrl}?{$fixtureParams}"), true)["data"]; $mainReferee = current(array_filter($fixture["referees"], fn($r) => $r["type_id"] === 6)); if ($mainReferee) { $refUrl = "https://api.sportmonks.com/v3/football/referees/{$mainReferee['referee_id']}"; $refParams = http_build_query(["api_token" => $apiToken]); $referee = json_decode(file_get_contents("{$refUrl}?{$refParams}"), true)["data"]; echo "Referee: {$referee['display_name']}\n"; } else { echo "No main referee assigned for this fixture.\n"; } ``` {% endtab %} {% endtabs %} #### Best practices 1. **Don't assume all five roles will be present.** Filter for the `type_id` you actually need (usually `6`, the main referee) rather than indexing by array position. 2. **Cache referee profile lookups.** A referee's biographical data doesn't change often, cache by `referee_id` rather than re-fetching on every fixture request. 3. **Use referee statistics for performance tracking**, not this include. If you're building card-count or penalty-given dashboards, use `include=statistics.details.type` on the standalone Referee endpoint instead. #### Related includes * [**Coaches**](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/coaches) - Similar fixture-level personnel include, but embeds full bio data directly (referees does not) * [**Participants**](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/participants) - Required for general match context #### Summary The `referees` include returns lean linking objects (`referee_id`, `type_id`) rather than full profiles, unlike `coaches`. Resolve `referee_id` via a separate call to the standalone Referee endpoint to get a name. Type values run from 6 (Referee) to 10 (VAR), but not all roles are guaranteed to appear on every fixture, even in leagues that use VAR. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/referees.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.