# Referees

Retrieve detailed referee information via one of our referees' endpoints. You can retrieve more detailed information by using the correct includes. This section will briefly discuss all the options available to request referees.

An overview of all the options available:

* **GET All Referees:** returns all the referees available within your subscription.
* **GET Referees by ID:** returns referee information from your requested referee ID.
* **GET Referees by Country ID:** returns referee information from your requested country ID.
* **GET Referees Search by Name:** returns all the referees that match your search query.

For all the referees; endpoints the base URL is the same: URL: `https://api.sportmonks.com/v3/football/referees` 

Per endpoint the rest of the URL requires additional information. We will explain this per endpoint.

## Requesting referees

### GET All Referees 

Gather an overview of all referees available in your subscription via the [GET All Referees endpoint](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees/get-all-referees#base-url) to get an overview of all referees within their subscription.

The URL to get all your referees is the same as the base URL for referees. All you have to do is authorize the request with your API token. Check our [authentication section](https://docs.sportmonks.com/v3/welcome/authentication) for more info.

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees?api_token=YOUR_TOKEN
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": [
    {
      "id": 37,
      "sport_id": 1,
      "country_id": null,
      "city_id": null,
      "common_name": "Craig Alexander Thomson",
      "firstname": null,
      "lastname": null,
      "name": "Craig Alexander Thomson",
      "display_name": "Craig Alexander Thomson",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    },
    {
      "id": 94,
      "sport_id": 1,
      "country_id": null,
      "city_id": null,
      "common_name": "Robert Madden",
      "firstname": null,
      "lastname": null,
      "name": "Robert Madden",
      "display_name": "Robert Madden",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    },
    //And more
```

</details>

You can see the referees' name, the unique referee id and some other data.

Now that you've requested all the referees, you also know their unique referee id. You can use this id in the second option: [GET Referee by ID.](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees/get-referee-by-id#base-url)

### GET Referee by ID&#x20;

This endpoint is useful if you only want information about one particular referee. You need to add the `referee_id` to your request:

`https://api.sportmonks.com/v3/football/referees`**`/{referee_id}`**

Let’s say we want the information about Crawford Allan. (referee id: 70306).

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees/70306?api_token=YOUR_TOKEN
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": {
    "id": 70306,
    "sport_id": 1,
    "country_id": 1161,
    "city_id": null,
    "common_name": "C. Allan",
    "firstname": "Crawford",
    "lastname": "Allan",
    "name": "Crawford Allan",
    "display_name": "Crawford Allan",
    "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
    "height": null,
    "weight": null,
    "date_of_birth": null,
    "gender": null
  },
```

</details>

### GET Referees by Country ID&#x20;

Let’s say, we want all Scottish referee&#x73;**.** You need to add the `country_id` to your request:

`https://api.sportmonks.com/v3/football/referees`**`/countries/{country_id}`**

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees/countries/1161?api_token=YOUR_TOKEN
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": [
    {
      "id": 32585,
      "sport_id": 1,
      "country_id": 1161,
      "city_id": null,
      "common_name": "C. Graham",
      "firstname": "Chris",
      "lastname": "Graham",
      "name": "Chris Graham",
      "display_name": "C. Graham",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    },
    {
      "id": 12118,
      "sport_id": 1,
      "country_id": 1161,
      "city_id": null,
      "common_name": "D. McGeachie",
      "firstname": "David",
      "lastname": "McGeachie",
      "name": "David McGeachie",
      "display_name": "D. McGeachie",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    },
 //And more!
```

</details>

### GET Referees Search by Name&#x20;

You want the information about your favourite referee. However, you don’t know the referee id or country id. Well, we have an endpoint to use his name and get the information you need. The [GET Referees Search by Name endpoint](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees/get-referees-search-by-name), in order to do this you need to add the `/search/{search_query}`to your request:

`https://api.sportmonks.com/v3/football/referees`**`/search/{search_query}`**

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees/search/crawford?api_token=YOUR_TOKEN
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": [
    {
      "id": 14854,
      "sport_id": 1,
      "country_id": 1161,
      "city_id": null,
      "common_name": "G. Crawford",
      "firstname": "Gordon",
      "lastname": "Crawford",
      "name": "Gordon Crawford",
      "display_name": "Gordon Crawford",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    },
    {
      "id": 70306,
      "sport_id": 1,
      "country_id": 1161,
      "city_id": null,
      "common_name": "C. Allan",
      "firstname": "Crawford",
      "lastname": "Allan",
      "name": "Crawford Allan",
      "display_name": "Crawford Allan",
      "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
      "height": null,
      "weight": null,
      "date_of_birth": null,
      "gender": null
    }
  ],
```

</details>

## Adding useful information&#x20;

As you’ve learnt in the [includes tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes), you can enrich your request with includes. This section will discuss some of the most common requests on the referees' endpoints.

First of all, you can find a list of all available includes on the [endpoint pages](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees). For the referees, the most commonly used includes is `statistics`.

For example, if we want statistics of Crawford Allan(referee id: 70306).

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees/70306?api_token=YOUR_TOKEN&include=statistics
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": {
    "id": 70306,
    "sport_id": 1,
    "country_id": 1161,
    "city_id": null,
    "common_name": "C. Allan",
    "firstname": "Crawford",
    "lastname": "Allan",
    "name": "Crawford Allan",
    "display_name": "Crawford Allan",
    "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
    "height": null,
    "weight": null,
    "date_of_birth": null,
    "gender": null,
    "statistics": [
      {
        "id": 8265,
        "referee_id": 70306,
        "season_id": 825
      },
      {
        "id": 10539,
        "referee_id": 70306,
        "season_id": 1931
      },
      {
        "id": 10561,
        "referee_id": 70306,
        "season_id": 1932
      },
      {
        "id": 10583,
        "referee_id": 70306,
        "season_id": 1933
      },
      {
        "id": 10593,
        "referee_id": 70306,
        "season_id": 1934
      },
      //And more
```

</details>

## Selecting and filtering

In our [filtering tutorial ](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields/filtering)you’ve learnt how to select specific fields or filter only on the data you’re interested in. By default, our API returns a set of data related to the referee. We can imagine you’re not interested in all the referee data the API returns. Let’s say you’re only interested in the referee name and image.

We’re going to use the [GET Referee by ID.](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/referees/get-referee-by-id#base-url) for this example.

You can add the `&select=` parameter followed by the fields you want. In our case: `name,image_path`. This results in the below request and response:

{% code overflow="wrap" %}

```javascript
https://api.sportmonks.com/v3/football/referees/70306?api_token=YOUR_TOKEN&select=name,image_path
```

{% endcode %}

<details>

<summary>Response</summary>

```javascript
{
  "data": {
    "name": "Crawford Allan",
    "image_path": "https://cdn.sportmonks.com/images/soccer/placeholder.png",
    "id": 70306,
    "country_id": 1161,
    "sport_id": 1,
    "city_id": null
  },
```

</details>

{% hint style="info" %}
Check our [filtering tutorial](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/filter-and-select-fields/filtering) for more information and tips.
{% endhint %}