# 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.