# Participants

### What does the include do?

The `participants` include provides comprehensive information about the teams (participants) involved in a specific fixture. This include gives you detailed data about each team including their name, logo, founding year, venue, and match-specific metadata such as home/away status and winner information.

### Why use participants?

The participants include is essential for:

* **Team identification**: Get team names, logos, and short codes for display
* **Match context**: Understand home/away dynamics and venue information
* **Result tracking**: Immediately identify which team won the match
* **Team profiles**: Access founding year, country, and team type information
* **UI/UX development**: Get all necessary team data for building match interfaces

In API 3.0, participants replaced the older `localTeam` and `visitorTeam` includes to support multi-sport data models.

### Requesting participants

To retrieve participant information for a fixture, use the following include:

```http
https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=participants
```

**Example:** Get participants for Manchester United vs Everton (fixture ID: example)

```
https://api.sportmonks.com/v3/football/fixtures/{fixture_ID}
?api_token=YOUR_TOKEN&include=participants
```

### Response structure

When you include `participants` in your request, you'll receive an array of two participant objects (home and away teams):

```json
{
  "data": {
    "id": 19427573,
    "name": "Manchester United vs Everton",
    "starting_at": "2025-11-24 20:00:00",
    ...other fixture data...,
    "participants": [
      {
        "id": 14,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 206,
        "gender": "male",
        "name": "Manchester United",
        "short_code": "MUN",
        "image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/teams\/14\/14.png",
        "founded": 1878,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-11-24 20:00:00",
        "meta": {
          "location": "home",
          "winner": false,
          "position": 10
        }
      },
      {
        "id": 13,
        "sport_id": 1,
        "country_id": 462,
        "venue_id": 343762,
        "gender": "male",
        "name": "Everton",
        "short_code": "EVE",
        "image_path": "https:\/\/cdn.sportmonks.com\/images\/soccer\/teams\/13\/13.png",
        "founded": 1878,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-11-24 20:00:00",
        "meta": {
          "location": "away",
          "winner": true,
          "position": 13
        }
      }
    ]
  }
}
```

### Field descriptions

#### Main participant fields

| Field            | Type    | Description                                                      |
| ---------------- | ------- | ---------------------------------------------------------------- |
| `id`             | integer | Unique identifier for this team                                  |
| `sport_id`       | integer | ID of the sport (1 = football/soccer)                            |
| `country_id`     | integer | ID of the team's country                                         |
| `venue_id`       | integer | ID of the team's home stadium/venue                              |
| `gender`         | string  | Gender of the team: "male", "female", or "mixed"                 |
| `name`           | string  | Full name of the team                                            |
| `short_code`     | string  | 3-letter abbreviation for the team (e.g., "MUN", "EVE")          |
| `image_path`     | string  | URL to the team's logo/crest image                               |
| `founded`        | integer | Year the team was founded                                        |
| `type`           | string  | Team type: "domestic" or "national"                              |
| `placeholder`    | boolean | Indicates if this is a placeholder team (TBD teams in cup draws) |
| `last_played_at` | string  | DateTime of the team's most recent match                         |

#### Meta object fields

The `meta` object contains fixture-specific information about the participant:

| Field           | Type    | Description                                           |
| --------------- | ------- | ----------------------------------------------------- |
| `meta.location` | string  | Team's location in this fixture: "home" or "away"     |
| `meta.winner`   | boolean | Whether this team won the match (true/false)          |
| `meta.position` | integer | Team's league table position at the time of the match |

### Understanding home vs away

In API 3.0, the distinction between home and away teams is provided in the `meta.location` field:

* **"home"**: The team playing at their home venue
* **"away"**: The visiting team

This is different from API 2.0 which used `localTeam` and `visitorTeam` includes.

```python
def identify_home_away(participants):
    home_team = next(p for p in participants if p['meta']['location'] == 'home')
    away_team = next(p for p in participants if p['meta']['location'] == 'away')
    return home_team, away_team
```

### Identifying the winner

The `meta.winner` field immediately tells you which team won the match:

```python
def get_winner(participants):
    winner = next((p for p in participants if p['meta']['winner'] == True), None)
    if winner:
        return f"{winner['name']} won the match"
    else:
        return "Match was a draw"
```

### Nested includes

The participants include does not have specific nested includes documented, but you can use the participant\_id to fetch more detailed team information using the Teams endpoints if needed.

### Code examples

#### Python example

```python
import requests

# API configuration
API_TOKEN = "YOUR_TOKEN"
FIXTURE_ID = 19427573

# Request participants
url = f"https://api.sportmonks.com/v3/football/fixtures/{FIXTURE_ID}"
params = {
    "api_token": API_TOKEN,
    "include": "participants"
}

response = requests.get(url, params=params)
data = response.json()

# Extract participants
participants = data['data'].get('participants', [])

# Identify home and away teams
home_team = next((p for p in participants if p['meta']['location'] == 'home'), None)
away_team = next((p for p in participants if p['meta']['location'] == 'away'), None)

# Display match information
print(f"Match: {home_team['name']} vs {away_team['name']}")
print(f"Home Team Founded: {home_team['founded']}")
print(f"Away Team Founded: {away_team['founded']}")
print(f"\nHome Team Position: {home_team['meta']['position']}")
print(f"Away Team Position: {away_team['meta']['position']}")

# Identify winner
winner = next((p for p in participants if p['meta']['winner'] == True), None)
if winner:
    print(f"\nWinner: {winner['name']}")
else:
    print("\nResult: Draw")

# Display team logos
print(f"\nHome Team Logo: {home_team['image_path']}")
print(f"Away Team Logo: {away_team['image_path']}")

# Example: Build a match header
def build_match_header(participants):
    """Build a formatted match header string"""
    home = next(p for p in participants if p['meta']['location'] == 'home')
    away = next(p for p in participants if p['meta']['location'] == 'away')
    
    header = f"""
╔══════════════════════════════════════════════╗
║  {home['short_code']} {home['name']:<30} (H) ║
║             vs                               ║
║  {away['short_code']} {away['name']:<30} (A) ║
╚══════════════════════════════════════════════╝
    """
    return header

print(build_match_header(participants))

# Example: Check for derby matches (same country, different teams)
def is_derby(participants):
    """Check if this is a derby match (teams from same city/country)"""
    if len(participants) != 2:
        return False
    
    country_ids = [p['country_id'] for p in participants]
    # Same country is a basic derby check
    is_same_country = len(set(country_ids)) == 1
    
    # More sophisticated derby detection would check city_id
    return is_same_country

if is_derby(participants):
    print("\n⚔️  This is a derby match!")
```

#### JavaScript example

```javascript
// API configuration
const API_TOKEN = "YOUR_TOKEN";
const FIXTURE_ID = 19427573;

// Request participants
async function getFixtureParticipants() {
    const url = `https://api.sportmonks.com/v3/football/fixtures/${FIXTURE_ID}`;
    const params = new URLSearchParams({
        api_token: API_TOKEN,
        include: "participants"
    });

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        
        const participants = data.data.participants || [];
        
        // Identify home and away teams
        const homeTeam = participants.find(p => p.meta.location === 'home');
        const awayTeam = participants.find(p => p.meta.location === 'away');
        
        // Display match information
        console.log(`Match: ${homeTeam.name} vs ${awayTeam.name}`);
        console.log(`Home Team Founded: ${homeTeam.founded}`);
        console.log(`Away Team Founded: ${awayTeam.founded}`);
        console.log(`\nHome Team Position: ${homeTeam.meta.position}`);
        console.log(`Away Team Position: ${awayTeam.meta.position}`);
        
        // Identify winner
        const winner = participants.find(p => p.meta.winner === true);
        if (winner) {
            console.log(`\nWinner: ${winner.name}`);
        } else {
            console.log("\nResult: Draw");
        }
        
        // Display team logos
        console.log(`\nHome Team Logo: ${homeTeam.image_path}`);
        console.log(`Away Team Logo: ${awayTeam.image_path}`);
        
        // Build match card in HTML
        buildMatchCard(participants);
        
    } catch (error) {
        console.error("Error fetching participants:", error);
    }
}

// Build HTML match card
function buildMatchCard(participants) {
    const homeTeam = participants.find(p => p.meta.location === 'home');
    const awayTeam = participants.find(p => p.meta.location === 'away');
    const winner = participants.find(p => p.meta.winner === true);
    
    const matchCard = document.createElement('div');
    matchCard.className = 'match-card';
    matchCard.innerHTML = `
        <div class="match-header">
            <h2>Match Details</h2>
        </div>
        <div class="teams-container">
            <div class="team home ${winner?.id === homeTeam.id ? 'winner' : ''}">
                <img src="${homeTeam.image_path}" alt="${homeTeam.name}" class="team-logo">
                <h3>${homeTeam.name}</h3>
                <p class="team-code">${homeTeam.short_code}</p>
                <p class="position">Position: ${homeTeam.meta.position}</p>
                <span class="location-badge">HOME</span>
            </div>
            <div class="vs">VS</div>
            <div class="team away ${winner?.id === awayTeam.id ? 'winner' : ''}">
                <img src="${awayTeam.image_path}" alt="${awayTeam.name}" class="team-logo">
                <h3>${awayTeam.name}</h3>
                <p class="team-code">${awayTeam.short_code}</p>
                <p class="position">Position: ${awayTeam.meta.position}</p>
                <span class="location-badge">AWAY</span>
            </div>
        </div>
        ${winner ? `<div class="result">Winner: ${winner.name}</div>` : '<div class="result">Draw</div>'}
    `;
    
    document.body.appendChild(matchCard);
}

// Check for placeholder teams (TBD in cup draws)
function hasPlaceholder(participants) {
    return participants.some(p => p.placeholder === true);
}

// Get team by location
function getTeamByLocation(participants, location) {
    return participants.find(p => p.meta.location === location);
}

// Example: Build team comparison
function compareTeams(participants) {
    const home = participants.find(p => p.meta.location === 'home');
    const away = participants.find(p => p.meta.location === 'away');
    
    return {
        experienceDiff: home.founded - away.founded,
        positionDiff: home.meta.position - away.meta.position,
        homeAdvantage: home.meta.location === 'home',
        homeName: home.name,
        awayName: away.name
    };
}

// Run the example
getFixtureParticipants();
```

### Common use cases

#### 1. Match header display

Create a visual match header for your application:

```python
def create_match_display(participants, fixture_name):
    home = next(p for p in participants if p['meta']['location'] == 'home')
    away = next(p for p in participants if p['meta']['location'] == 'away')
    
    display = {
        'fixture_name': fixture_name,
        'home': {
            'name': home['name'],
            'short_code': home['short_code'],
            'logo': home['image_path'],
            'position': home['meta']['position']
        },
        'away': {
            'name': away['name'],
            'short_code': away['short_code'],
            'logo': away['image_path'],
            'position': away['meta']['position']
        }
    }
    
    return display
```

#### 2. Historical performance tracking

Track how teams perform home vs away:

```python
def analyze_home_away_performance(fixtures_with_participants):
    """Analyze team performance based on home/away status"""
    team_stats = {}
    
    for fixture in fixtures_with_participants:
        participants = fixture.get('participants', [])
        
        for participant in participants:
            team_id = participant['id']
            location = participant['meta']['location']
            won = participant['meta']['winner']
            
            if team_id not in team_stats:
                team_stats[team_id] = {
                    'name': participant['name'],
                    'home_wins': 0,
                    'away_wins': 0,
                    'home_games': 0,
                    'away_games': 0
                }
            
            if location == 'home':
                team_stats[team_id]['home_games'] += 1
                if won:
                    team_stats[team_id]['home_wins'] += 1
            else:
                team_stats[team_id]['away_games'] += 1
                if won:
                    team_stats[team_id]['away_wins'] += 1
    
    return team_stats
```

#### 3. Cup draw management

Handle TBD teams in cup competitions:

```python
def format_cup_match(participants):
    """Format cup match display, handling TBD teams"""
    display_parts = []
    
    for participant in participants:
        if participant['placeholder']:
            display_parts.append(f"TBD ({participant['name']})")
        else:
            display_parts.append(participant['name'])
    
    return " vs ".join(display_parts)
```

#### 4. Team logo gallery

Build a logo display for multiple fixtures:

```python
def get_all_team_logos(fixtures_with_participants):
    """Extract unique team logos from multiple fixtures"""
    logos = {}
    
    for fixture in fixtures_with_participants:
        for participant in fixture.get('participants', []):
            team_id = participant['id']
            if team_id not in logos:
                logos[team_id] = {
                    'name': participant['name'],
                    'short_code': participant['short_code'],
                    'logo_url': participant['image_path']
                }
    
    return logos
```

### Best practices

1. **Always check meta.location**: Don't assume array order for home/away teams. Always use `meta.location` to identify teams correctly.
2. **Handle placeholder teams**: In cup competitions, check the `placeholder` field to handle TBD teams appropriately.
3. **Cache team logos**: Team logos rarely change. Cache them locally to reduce bandwidth and improve performance.
4. **Use short\_code for displays**: The 3-letter short code is perfect for space-constrained displays (mobile, scoreboards).
5. **Combine with other includes**: Use `&include=participants,scores,events` to get complete match data in one request.
6. **Check for national teams**: Use the `type` field to distinguish between club teams ("domestic") and national teams ("national").

### Differences from API 2.0

In API 2.0, teams were accessed via:

* `localTeam` (home team)
* `visitorTeam` (away team)

In API 3.0, this changed to:

* `participants` (array containing both teams)
* Use `meta.location` to identify home/away

**Migration example:**

```python
# API 2.0
home_team = fixture['localTeam']['data']
away_team = fixture['visitorTeam']['data']

# API 3.0
participants = fixture['participants']
home_team = next(p for p in participants if p['meta']['location'] == 'home')
away_team = next(p for p in participants if p['meta']['location'] == 'away')
```

### Related includes

* [**Scores**](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/includes/scores) - Combine with scores to show team names and final results
* [**Lineups**](https://claude.ai/football/tutorials-and-guides/tutorials/includes/lineups) - Get player lineups for each participant
* [**Events**](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/includes/events) - See which team scored goals and received cards
* [**Venue**](https://docs.sportmonks.com/football/endpoints-and-entities/endpoints/venues) - Get detailed venue information for the home team

### Summary

The `participants` include provides essential team information for fixtures including names, logos, home/away status, and winner information. The `meta` object contains fixture-specific data like location and winner status, making it easy to build match displays and track team performance. Always use `meta.location` to correctly identify home and away teams in API 3.0.


---

# Agent Instructions: 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:

```
GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/participants.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.