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:

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):

{
  "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.

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:

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

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

// 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:

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:

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:

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:

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:

# 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 - Combine with scores to show team names and final results

• Lineups - Get player lineups for each participant

• Events - See which team scored goals and received cards

• Venue - 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.