Scores

What does the include do?

The scores include allows you to retrieve detailed information about the scores within a football match from both participants (home and away teams). Including scores in your API requests provides comprehensive scoring data including 1st half, 2nd half, extra time, penalty shootout results, and current match score.

Why use scores?

The scores include is essential for:

• Live match tracking: Display real-time score updates during matches

• Historical score analysis: Analyse how teams performed across different match periods

• Comeback patterns: Identify teams that score more in second halves

• Extra time performance: Track team performance in high-pressure situations

• Statistical analysis: Build datasets for scoring pattern analysis

Requesting scores

To retrieve scores for a fixture, use the following include:

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

Example: Get scores for Napoli vs Atalanta (fixture ID: 19424997)

https://api.sportmonks.com/v3/football/fixtures/19424997
?api_token=YOUR_TOKEN&include=scores

Response structure

When you include scores in your request, you'll receive an array of score objects for each match period:

{
  "data": {
    "id": 19424997,
    "sport_id": 1,
    "league_id": 384,
    "season_id": 25533,
    "stage_id": 77476851,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 371860,
    "state_id": 5,
    "venue_id": 134,
    "name": "Napoli vs Atalanta",
    "starting_at": "2025-11-22 19:45:00",
    "result_info": "Napoli won after full-time.",
    "leg": "1\/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "has_premium_odds": true,
    "starting_at_timestamp": 1763840700,
    "scores": [
      {
        "id": 17490807,
        "fixture_id": 19424997,
        "type_id": 48996,
        "participant_id": 708,
        "score": {
          "goals": 1,
          "participant": "away"
        },
        "description": "2ND_HALF_ONLY"
      },
      {
        "id": 17490806,
        "fixture_id": 19424997,
        "type_id": 48996,
        "participant_id": 597,
        "score": {
          "goals": 0,
          "participant": "home"
        },
        "description": "2ND_HALF_ONLY"
      },
      {
        "id": 17490045,
        "fixture_id": 19424997,
        "type_id": 1525,
        "participant_id": 597,
        "score": {
          "goals": 3,
          "participant": "home"
        },
        "description": "CURRENT"
      },
      {
        "id": 17490044,
        "fixture_id": 19424997,
        "type_id": 1525,
        "participant_id": 708,
        "score": {
          "goals": 1,
          "participant": "away"
        },
        "description": "CURRENT"
      },
      {
        "id": 17490047,
        "fixture_id": 19424997,
        "type_id": 1,
        "participant_id": 597,
        "score": {
          "goals": 3,
          "participant": "home"
        },
        "description": "1ST_HALF"
      },
      {
        "id": 17490048,
        "fixture_id": 19424997,
        "type_id": 2,
        "participant_id": 708,
        "score": {
          "goals": 1,
          "participant": "away"
        },
        "description": "2ND_HALF"
      },
      {
        "id": 17490049,
        "fixture_id": 19424997,
        "type_id": 2,
        "participant_id": 597,
        "score": {
          "goals": 3,
          "participant": "home"
        },
        "description": "2ND_HALF"
      },
      {
        "id": 17490046,
        "fixture_id": 19424997,
        "type_id": 1,
        "participant_id": 708,
        "score": {
          "goals": 0,
          "participant": "away"
        },
        "description": "1ST_HALF"
      }
    ]
  }
}

Field descriptions

Field	Type	Description
id	integer	Unique identifier for this score entry
fixture_id	integer	ID of the fixture this score belongs to
type_id	integer	Type identifier indicating the score period (see Score Types below)
participant_id	integer	ID of the team (participant) this score belongs to
score	object	Score object containing goals and participant location
score.goals	integer	Number of goals scored by this participant in this period
score.participant	string	Team location: "home" or "away"
description	string	Human-readable description of the score type

Score types and descriptions

When you use the scores include for a regular match, you'll get different types of scores based on the match state:

Regular Match (90 minutes)

Description	Explanation
1ST_HALF	Goals scored during the first 45 minutes
2ND_HALF_ONLY	Goals scored during the second 45 minutes only (not cumulative)
2ND_HALF	Cumulative score after both halves (1st half + 2nd half)
CURRENT	The current/final score of the match

Extended match (Extra Time)

If the match goes into extra time, you'll see additional score types:

Description	Explanation
EXTRA_TIME	Goals scored during extra time (both periods combined)
EXTRA_TIME_ONLY	Goals scored in extra time only (not including regular time)
CURRENT	The updated current score including extra time

Penalty Shootout

If the match goes to penalties, you'll see:

Description	Explanation
PENALTIES	Number of successful penalty kicks in the shootout
CURRENT	Final score including all periods

A few examples (not all scores) from the Euro 2024 quarter-final (Spain vs Germany):

"scores": [
  {
    "description": "1ST_HALF",
    "score": {
      "goals": 0,
      "participant": "home"
    }
  },
  {
    "description": "2ND_HALF",
    "score": [
      {
        "goals": 1,
        "participant": "home"
      },
      {
        "goals": 1,
        "participant": "away"
      }
    ]
  },
  {
    "description": "EXTRA_TIME",
    "score": {
      "goals": 1,
      "participant": "home"
    }
  },
  {
    "description": "CURRENT",
    "score": {
      "goals": 2,
      "participant": "home"
    }
  }
]

Displaying current score

To display the latest scores for a game, always use the CURRENT indicator. This ensures you show the most up-to-date score regardless of whether the match included extra time or penalties.

def get_current_score(scores_data):
    """Extract current score for both teams"""
    current_scores = {}
    
    for score in scores_data:
        if score['description'] == 'CURRENT':
            participant = score['score']['participant']
            goals = score['score']['goals']
            current_scores[participant] = goals
    
    return current_scores

# Usage
current = get_current_score(fixture_scores)
print(f"Home: {current['home']} - Away: {current['away']}")

Nested includes

The scores include supports the following nested includes for additional information:

scores.type

Get detailed information about the score type:

https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=scores.type

This returns the type object with details about the score period.

scores.participant

Get detailed information about the team (participant):

https://api.sportmonks.com/v3/football/fixtures/{fixture_id}
?api_token=YOUR_TOKEN&include=scores.participant

This returns team information including name, logo, and other details.

Example with nested includes:

{
  "scores": [
    {
      "id": 19424997,
      "fixture_id": 19424997,
      "type_id": 48996,
      "participant_id": 708,
      "score": {
        "goals": 1,
        "participant": "away"
      },
      "description": "2ND_HALF_ONLY",
      "participant": {
        "id": 708,
        "sport_id": 1,
        "country_id": 251,
        "venue_id": 193,
        "gender": "male",
        "name": "Atalanta",
        "short_code": "ATA",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/4/708.png",
        "founded": 1907,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-11-26 20:00:00"
      }
    },
    {
      "id": 17490806,
      "fixture_id": 19424997,
      "type_id": 48996,
      "participant_id": 597,
      "score": {
        "goals": 0,
        "participant": "home"
      },
      "description": "2ND_HALF_ONLY",
      "participant": {
        "id": 597,
        "sport_id": 1,
        "country_id": 251,
        "venue_id": 134,
        "gender": "male",
        "name": "Napoli",
        "short_code": "NAP",
        "image_path": "https://cdn.sportmonks.com/images/soccer/teams/21/597.png",
        "founded": 1926,
        "type": "domestic",
        "placeholder": false,
        "last_played_at": "2025-11-25 20:00:00"
      }
    }
  ]
}

Code examples

Python Example

import requests

# API configuration
API_TOKEN = "YOUR_TOKEN"
FIXTURE_ID = 19424997

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

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

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

# Parse scores by description type
score_by_type = {}
for score in scores:
    description = score['description']
    if description not in score_by_type:
        score_by_type[description] = {'home': None, 'away': None}
    
    participant_type = score['score']['participant']
    score_by_type[description][participant_type] = {
        'goals': score['score']['goals'],
        'team': score.get('participant', {}).get('name', 'Unknown')
    }

# Display current score
if 'CURRENT' in score_by_type:
    current = score_by_type['CURRENT']
    print(f"Final Score: {current['home']['team']} {current['home']['goals']} - "
          f"{current['away']['goals']} {current['away']['team']}")

# Display half-time scores
if '1ST_HALF' in score_by_type:
    ht = score_by_type['1ST_HALF']
    print(f"Half Time: {ht['home']['goals']} - {ht['away']['goals']}")

# Display second half goals only
if '2ND_HALF_ONLY' in score_by_type:
    sh = score_by_type['2ND_HALF_ONLY']
    print(f"Second Half Goals: {sh['home']['goals']} - {sh['away']['goals']}")

# Analyze scoring patterns
def analyze_scoring_patterns(scores):
    """Analyze when goals were scored"""
    first_half = {'home': 0, 'away': 0}
    second_half = {'home': 0, 'away': 0}
    
    for score in scores:
        goals = score['score']['goals']
        participant = score['score']['participant']
        
        if score['description'] == '1ST_HALF':
            first_half[participant] = goals
        elif score['description'] == '2ND_HALF_ONLY':
            second_half[participant] = goals
    
    print("\nScoring Pattern Analysis:")
    print(f"Home team - 1st half: {first_half['home']}, 2nd half: {second_half['home']}")
    print(f"Away team - 1st half: {first_half['away']}, 2nd half: {second_half['away']}")

analyze_scoring_patterns(scores)

JavaScript example

// API configuration
const API_TOKEN = "YOUR_TOKEN";
const FIXTURE_ID = 19424997;

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

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        
        const scores = data.data.scores || [];
        
        // Parse scores by description type
        const scoreByType = {};
        scores.forEach(score => {
            const description = score.description;
            if (!scoreByType[description]) {
                scoreByType[description] = { home: null, away: null };
            }
            
            const participantType = score.score.participant;
            scoreByType[description][participantType] = {
                goals: score.score.goals,
                team: score.participant?.name || 'Unknown'
            };
        });
        
        // Display current score
        if (scoreByType['CURRENT']) {
            const current = scoreByType['CURRENT'];
            console.log(`Final Score: ${current.home.team} ${current.home.goals} - ${current.away.goals} ${current.away.team}`);
        }
        
        // Display half-time scores
        if (scoreByType['1ST_HALF']) {
            const ht = scoreByType['1ST_HALF'];
            console.log(`Half Time: ${ht.home.goals} - ${ht.away.goals}`);
        }
        
        // Display second half goals only
        if (scoreByType['2ND_HALF_ONLY']) {
            const sh = scoreByType['2ND_HALF_ONLY'];
            console.log(`Second Half Goals: ${sh.home.goals} - ${sh.away.goals}`);
        }
        
        // Analyze scoring patterns
        analyzeScoringPatterns(scores);
        
    } catch (error) {
        console.error("Error fetching scores:", error);
    }
}

function analyzeScoringPatterns(scores) {
    const firstHalf = { home: 0, away: 0 };
    const secondHalf = { home: 0, away: 0 };
    
    scores.forEach(score => {
        const goals = score.score.goals;
        const participant = score.score.participant;
        
        if (score.description === '1ST_HALF') {
            firstHalf[participant] = goals;
        } else if (score.description === '2ND_HALF_ONLY') {
            secondHalf[participant] = goals;
        }
    });
    
    console.log("\nScoring Pattern Analysis:");
    console.log(`Home team - 1st half: ${firstHalf.home}, 2nd half: ${secondHalf.home}`);
    console.log(`Away team - 1st half: ${firstHalf.away}, 2nd half: ${secondHalf.away}`);
}

// Display scores in a table format
function displayScoresTable(scores) {
    const table = document.createElement('table');
    table.innerHTML = `
        <thead>
            <tr>
                <th>Period</th>
                <th>Home</th>
                <th>Away</th>
            </tr>
        </thead>
        <tbody>
        </tbody>
    `;
    
    const tbody = table.querySelector('tbody');
    const scoreTypes = ['1ST_HALF', '2ND_HALF_ONLY', 'EXTRA_TIME', 'CURRENT'];
    
    scoreTypes.forEach(type => {
        const homeScore = scores.find(s => s.description === type && s.score.participant === 'home');
        const awayScore = scores.find(s => s.description === type && s.score.participant === 'away');
        
        if (homeScore && awayScore) {
            const row = tbody.insertRow();
            row.innerHTML = `
                <td>${type.replace(/_/g, ' ')}</td>
                <td>${homeScore.score.goals}</td>
                <td>${awayScore.score.goals}</td>
            `;
        }
    });
    
    document.body.appendChild(table);
}

// Run the example
getFixtureScores();

Common use cases

1. Live Score Display

Display live scores that automatically update with the most current match state:

def format_live_score(scores):
    current = next((s for s in scores if s['description'] == 'CURRENT'), None)
    if not current:
        return "Score not available"
    
    home_score = next(s for s in scores if s['description'] == 'CURRENT' and s['score']['participant'] == 'home')
    away_score = next(s for s in scores if s['description'] == 'CURRENT' and s['score']['participant'] == 'away')
    
    return f"{home_score['score']['goals']} - {away_score['score']['goals']}"

2. Half-time vs Full-time analysis

Compare first half and full-time scores to identify second-half comebacks:

def check_comeback(scores):
    ht_home = next((s['score']['goals'] for s in scores if s['description'] == '1ST_HALF' and s['score']['participant'] == 'home'), 0)
    ht_away = next((s['score']['goals'] for s in scores if s['description'] == '1ST_HALF' and s['score']['participant'] == 'away'), 0)
    
    ft_home = next((s['score']['goals'] for s in scores if s['description'] == 'CURRENT' and s['score']['participant'] == 'home'), 0)
    ft_away = next((s['score']['goals'] for s in scores if s['description'] == 'CURRENT' and s['score']['participant'] == 'away'), 0)
    
    if ht_home > ht_away and ft_home < ft_away:
        return "Away team made a comeback!"
    elif ht_away > ht_home and ft_away < ft_home:
        return "Home team made a comeback!"
    else:
        return "No comeback occurred"

3. Statistical analysis

Build datasets for machine learning or statistical analysis:

def build_scoring_dataset(fixtures_with_scores):
    dataset = []
    for fixture in fixtures_with_scores:
        scores = fixture.get('scores', [])
        
        record = {
            'fixture_id': fixture['id'],
            'home_1st_half': 0,
            'away_1st_half': 0,
            'home_2nd_half': 0,
            'away_2nd_half': 0,
            'home_final': 0,
            'away_final': 0
        }
        
        for score in scores:
            desc = score['description']
            part = score['score']['participant']
            goals = score['score']['goals']
            
            if desc == '1ST_HALF':
                record[f'{part}_1st_half'] = goals
            elif desc == '2ND_HALF_ONLY':
                record[f'{part}_2nd_half'] = goals
            elif desc == 'CURRENT':
                record[f'{part}_final'] = goals
        
        dataset.append(record)
    
    return dataset

Best practices

1. Always use CURRENT for live updates: Don't rely on calculating 1ST_HALF + 2ND_HALF, as extra time and penalties will make this incorrect.

2. Check for extra time and penalties: Before displaying results, check if EXTRA_TIME or PENALTIES descriptions exist.

3. Use nested includes for complete data: Include scores.participant to get team names and logos without additional API calls.

4. Cache historical data: Scores don't change after a match ends. Cache completed matches to reduce API calls.

5. Handle missing data gracefully: Not all matches have all score types immediately available during live matches.

Related includes

• Participants - Get team information for the scoring teams

• Events - See individual goal events with scorers

• Statistics - Combine scores with match statistics for analysis

• Periods - Get timing information for when goals were scored

Summary

The scores include provides comprehensive scoring data for all match periods including regular time, extra time, and penalties. With support for nested includes and clear score type descriptions, it enables accurate live score displays, statistical analysis, and historical score tracking. Always use the CURRENT description to display the most up-to-date score.