Periods

What does the include do?

The periods and detailedPeriods includes allow you to retrieve detailed information about different periods within a football match, including regular time, extra time, and penalties. These includes provide comprehensive timing data including the current minute, seconds elapsed, period start/end times, and whether the period is currently active (ticking).

Why use periods?

The periods include is essential for:

• Live match tracking: Display accurate match time with minute and second precision

• Match state management: Know which period is currently being played

• Time-based analysis: Analyse events by period (first half, second half, extra time)

• Broadcast applications: Show precise match timing for live streams

• Statistical analysis: Break down team performance by match period

• Injury time tracking: Monitor added time in each period

In most cases, periods is enough for standard match timing. Use detailedPeriods when you need to split extra time into both halves for more precise reporting and analysis.

What is the difference between the periods and detailedPeriods includes?

The only difference between these includes is in Extra Time:

• periods returns Extra Time as a single period.

• detailedPeriods returns Extra Time 1st Half and Extra Time 2nd Half as two separate 15-minute periods.

Requesting periods

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

// Returns Extra Time as a single period
https://api.sportmonks.com/v3/football/fixtures/<fixture_id>
?api_token=YOUR_TOKEN&include=periods

// Returns Extra Time as two separate periods, one for each ET half
https://api.sportmonks.com/v3/football/fixtures/<fixture_id>
?api_token=YOUR_TOKEN&include=detailedPeriods

Example: Get periods for Real Madrid vs FC Barcelona (fixture ID: 19439347)

// Single Extra Time period
https://api.sportmonks.com/v3/football/fixtures/19439347
?api_token=YOUR_TOKEN&include=periods

// Separate Extra Time periods
https://api.sportmonks.com/v3/football/fixtures/19439347
?api_token=YOUR_TOKEN&include=detailedPeriods

Response structure

Using the periods include

When you include periods in your request, you'll receive an array of period objects for each match period. Extra time is returned as a single period object:

{
  "data": {
    "id": 19606957,
    "sport_id": 1,
    "league_id": 732,
    "season_id": 26618,
    "stage_id": 77479086,
    "group_id": null,
    "aggregate_id": null,
    "round_id": null,
    "state_id": 8,
    "venue_id": 160,
    "name": "Germany vs Paraguay",
    "starting_at": "2026-06-29 20:30:00",
    "result_info": "Paraguay won after penalties.",
    "leg": "1/1",
    "details": "Match 74",
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "has_premium_odds": true,
    "starting_at_timestamp": 1782765000,
    "periods": [
      {
        "id": 7000093,
        "fixture_id": 19606957,
        "type_id": 1,
        "started": 1782765014,
        "ended": 1782768036,
        "counts_from": 0,
        "ticking": false,
        "sort_order": 1,
        "description": "1st-half",
        "time_added": 5,
        "period_length": 45,
        "minutes": 50,
        "seconds": 22,
        "has_timer": false
      },
      {
        "id": 7000096,
        "fixture_id": 19606957,
        "type_id": 2,
        "started": 1782769088,
        "ended": 1782772114,
        "counts_from": 45,
        "ticking": false,
        "sort_order": 2,
        "description": "2nd-half",
        "time_added": 5,
        "period_length": 45,
        "minutes": 95,
        "seconds": 26,
        "has_timer": false
      },
      {
        "id": 7000099,
        "fixture_id": 19606957,
        "type_id": 3,
        "started": 1782772425,
        "ended": 1782774772,
        "counts_from": 90,
        "ticking": false,
        "sort_order": 3,
        "description": "extra-time",
        "time_added": 7,
        "period_length": 30,
        "minutes": 129,
        "seconds": 7,
        "has_timer": false
      },
      {
        "id": 7000104,
        "fixture_id": 19606957,
        "type_id": 5,
        "started": 1782773720,
        "ended": 1782775715,
        "counts_from": null,
        "ticking": false,
        "sort_order": 4,
        "description": "penalties",
        "time_added": null,
        "period_length": 0,
        "minutes": null,
        "seconds": 0,
        "has_timer": false
      }
    ]
  }
}

Using the detailedPeriods include

Field descriptions

Field	Type	Description
id	integer	Unique identifier for this period
fixture_id	integer	ID of the fixture this period belongs to
type_id	integer	Type identifier for the period (see Period Types below)
started	integer	UNIX timestamp of when the period started
ended	integer/null	UNIX timestamp of when the period ended (null if ongoing)
counts_from	integer	Minute from which this period starts counting (e.g., 0 for 1st half, 45 for 2nd half)
ticking	boolean	Whether the period is currently active/being played
sort_order	integer	Sorting order of the period (1 = first, 2 = second, etc.)
description	string	Human-readable description of the period
time_added	integer/null	Additional injury/stoppage time added to the period (in minutes)
period_length	integer	Standard length of the period in minutes (usually 45 for regular time)
minutes	integer	Current minute within the match (cumulative)
seconds	integer	Seconds after the current minute (0-59)
has_timer	boolean	Whether detailed timer information (minutes/seconds) is available

Period types

The type_id field indicates what type of period this represents:

Type ID	Description	counts_from	period_length	Available in include
1	First Half (1ST_HALF)	0	45	periods & detailedPeriods
2	Second Half (2ND_HALF)	45	45	periods & detailedPeriods
3	Extra Time	90	30	periods only
5314	Extra Time - First Half	90	15	detailedPeriods only
39	Extra Time - Second Half	105	15	detailedPeriods only
5	Penalty Shootout	120	N/A	periods & detailedPeriods

Understanding period timing

counts_from

This field indicates the starting minute for the period:

• 1st half: counts_from = 0 (minutes 0-45)

• 2nd half: counts_from = 45 (minutes 45-90)

• Extra time (combined): counts_from = 90 (minutes 90-120)

• Extra time 1st: counts_from = 90 (minutes 90-105)

• Extra time 2nd: counts_from = 105 (minutes 105-120)

minutes and seconds

These fields provide the current match time:

• minutes: Cumulative minute count from match start (e.g., 47 means 47th minute)

• seconds: Seconds within current minute (0-59)

Example: minutes = 47, seconds = 23 means the match is at 47:23

ticking

• true: This period is currently active (match is live in this period)

• false: This period is not currently active (e.g. period has ended or is interrupted)

time_added (Injury time)

The additional minutes added to the period for stoppages:

• Usually 1-5 minutes in regular time

• Shows as "45+2" in match displays when 2 minutes added to 1st half

Current period include

In addition to the periods include, you can use the currentPeriod include for a more convenient way to get only the active period:

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

This returns only the period that is currently ticking (or null if match hasn't started or has ended).

Nested includes

The periods include supports the following nested includes:

periods.type

Get detailed information about the period type:

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

periods.events

Get all events that occurred during this specific period:

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

periods.statistics

Get statistics specific to this period:

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

Code examples

Python example

import requests
from datetime import datetime

# API configuration
API_TOKEN = "YOUR_TOKEN"
FIXTURE_ID = 19439347

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

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

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

# Display all periods
for period in periods:
    print(f"\n{period['description']}:")
    print(f"  Started: {datetime.fromtimestamp(period['started'])}")
    if period['ended']:
        print(f"  Ended: {datetime.fromtimestamp(period['ended'])}")
        duration = period['ended'] - period['started']
        print(f"  Duration: {duration // 60} minutes")
    print(f"  Ticking: {period['ticking']}")
    if period['time_added']:
        print(f"  Injury time: +{period['time_added']} minutes")

# Find current/active period
def get_current_period(periods):
    """Get the currently active period"""
    return next((p for p in periods if p['ticking']), None)

current = get_current_period(periods)
if current:
    print(f"\n🔴 LIVE: Currently in {current['description']}")
    print(f"⏱️  Match time: {current['minutes']}:{current['seconds']:02d}")
else:
    print("\n✅ Match ended or not started")

# Calculate total match time
def calculate_total_time(periods):
    """Calculate total playing time including injury time"""
    total_minutes = 0
    for period in periods:
        if period['ended']:
            duration_seconds = period['ended'] - period['started']
            total_minutes += duration_seconds // 60
    return total_minutes

total_time = calculate_total_time(periods)
print(f"\n⏱️  Total playing time: {total_time} minutes")

# Track injury time patterns
def analyze_injury_time(periods):
    """Analyse injury time added in each period"""
    injury_time = {}
    for period in periods:
        if period['time_added']:
            injury_time[period['description']] = period['time_added']
    return injury_time

injury_analysis = analyze_injury_time(periods)
print(f"\n🚑 Injury time analysis:")
for period_name, minutes in injury_analysis.items():
    print(f"  {period_name}: +{minutes} minutes")

# Check if match went to extra time
def has_extra_time(periods):
    """Check if match included extra time"""
    return any(p['description'] == 'extra-time' for p in periods)

def has_penalties(periods):
    """Check if match went to penalties"""
    return any(p['description'] == 'penalties' for p in periods)

if has_extra_time(periods):
    print("\n⏱️  Match included extra time")
if has_penalties(periods):
    print("🎯 Match decided by penalties")

JavaScript example

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

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

    try {
        const response = await fetch(`${url}?${params}`);
        const data = await response.json();
        
        const periods = data.data.periods || [];
        
        // Display all periods
        periods.forEach(period => {
            console.log(`\n${period.description}:`);
            console.log(`  Started: ${new Date(period.started * 1000).toLocaleString()}`);
            if (period.ended) {
                console.log(`  Ended: ${new Date(period.ended * 1000).toLocaleString()}`);
                const duration = Math.floor((period.ended - period.started) / 60);
                console.log(`  Duration: ${duration} minutes`);
            }
            console.log(`  Ticking: ${period.ticking}`);
            if (period.time_added) {
                console.log(`  Injury time: +${period.time_added} minutes`);
            }
        });
        
        // Find current period
        const currentPeriod = getCurrentPeriod(periods);
        if (currentPeriod) {
            console.log(`\n🔴 LIVE: Currently in ${currentPeriod.description}`);
            console.log(`⏱️  Match time: ${currentPeriod.minutes}:${String(currentPeriod.seconds).padStart(2, '0')}`);
            
            // Display live timer
            displayLiveTimer(currentPeriod);
        } else {
            console.log("\n✅ Match ended or not started");
        }
        
        // Calculate total time
        const totalTime = calculateTotalTime(periods);
        console.log(`\n⏱️  Total playing time: ${totalTime} minutes`);
        
        // Check match extras
        if (hasExtraTime(periods)) {
            console.log("⏱️  Match included extra time");
        }
        if (hasPenalties(periods)) {
            console.log("🎯 Match decided by penalties");
        }
        
    } catch (error) {
        console.error("Error fetching periods:", error);
    }
}

function getCurrentPeriod(periods) {
    return periods.find(p => p.ticking === true);
}

function calculateTotalTime(periods) {
    return periods.reduce((total, period) => {
        if (period.ended) {
            const durationMinutes = Math.floor((period.ended - period.started) / 60);
            return total + durationMinutes;
        }
        return total;
    }, 0);
}

function hasExtraTime(periods) {
    return periods.some(p => p.type_id === 3);
}

function hasPenalties(periods) {
    return periods.some(p => p.type_id === 5);
}

// Display live match timer
function displayLiveTimer(period) {
    const timerDiv = document.createElement('div');
    timerDiv.className = 'live-timer';
    timerDiv.innerHTML = `
        <div class="timer-container">
            <div class="period-name">${period.description}</div>
            <div class="match-time">${period.minutes}:${String(period.seconds).padStart(2, '0')}</div>
            ${period.time_added ? `<div class="injury-time">+${period.time_added} min</div>` : ''}
            <div class="live-indicator">🔴 LIVE</div>
        </div>
    `;
    document.body.appendChild(timerDiv);
}

// Build period timeline visualization
function buildPeriodTimeline(periods) {
    const timeline = document.createElement('div');
    timeline.className = 'period-timeline';
    
    periods.forEach((period, index) => {
        const periodBlock = document.createElement('div');
        periodBlock.className = `period-block ${period.ticking ? 'active' : 'completed'}`;
        periodBlock.innerHTML = `
            <div class="period-label">${period.description}</div>
            <div class="period-time">${period.counts_from}-${period.counts_from + period.period_length}'</div>
            ${period.time_added ? `<div class="added-time">+${period.time_added}'</div>` : ''}
        `;
        timeline.appendChild(periodBlock);
    });
    
    document.body.appendChild(timeline);
}

// Format match time display
function formatMatchTime(period) {
    const baseMinute = period.minutes;
    const seconds = period.seconds;
    
    // Check if in injury time
    const regularTime = period.counts_from + period.period_length;
    if (baseMinute >= regularTime && period.time_added) {
        const injuryMinute = baseMinute - regularTime;
        return `${regularTime}+${injuryMinute}:${String(seconds).padStart(2, '0')}`;
    }
    
    return `${baseMinute}:${String(seconds).padStart(2, '0')}`;
}

// Run the example
getFixturePeriods();

Common use cases

1. Live match timer display

Display accurate live match time with injury time:

def format_match_time(period):
    """Format match time for display"""
    minutes = period['minutes']
    seconds = period['seconds']
    regular_time = period['counts_from'] + period['period_length']
    
    # Check if in injury time
    if minutes >= regular_time and period['time_added']:
        injury_minute = minutes - regular_time
        return f"{regular_time}+{injury_minute}:{seconds:02d}"
    
    return f"{minutes}:{seconds:02d}"

2. Period-based statistics

Analyze team performance by period:

def analyze_by_period(fixtures_with_periods_and_events):
    """Analyse goals scored by period"""
    period_stats = {
        '1ST_HALF': {'goals': 0},
        '2ND_HALF': {'goals': 0},
        'EXTRA_TIME': {'goals': 0}
    }
    
    for fixture in fixtures_with_periods_and_events:
        events = fixture.get('events', [])
        for event in events:
            if event['type_id'] == 14:  # Goal
                period_id = event['period_id']
                period = next((p for p in fixture['periods'] if p['id'] == period_id), None)
                if period:
                    period_stats[period['description']]['goals'] += 1
    
    return period_stats

3. Match state detection

Determine current match state:

def get_match_state(periods):
    """Determine current match state"""
    current = next((p for p in periods if p['ticking']), None)
    
    if not current:
        if any(p['ended'] for p in periods):
            return "FINISHED"
        return "NOT_STARTED"
    
    if current['type_id'] == 1:
        return "FIRST_HALF"
    elif current['type_id'] == 2:
        return "SECOND_HALF"
    elif current['type_id'] == 3:
        return "EXTRA_TIME"
    elif current['type_id'] == 5:
        return "PENALTIES"
    
    return "UNKNOWN"

Best practices

1. Use has_timer to check data availability: Not all matches have detailed timer information. Check has_timer before displaying seconds.

2. Handle null ended timestamps: For live matches, ended will be null for the current period.

3. Use currentPeriod for live updates: If you only need the active period, use include=currentPeriod instead of fetching all periods.

4. Calculate injury time correctly: Display as "45+2" not "47" when showing injury time to users.

5. Check ticking for live status: The ticking field is the most reliable way to determine if a period is currently active.

6. Sort by sort_order: Always use sort_order to display periods in chronological order.

7. Cache completed periods: Period data doesn't change after a period ends. Cache historical periods to reduce API calls.

Related includes

• Events - Cross-reference events with periods to show when they occurred

• Statistics - Get period-specific statistics

• States - Understand match state transitions

• Scores - See scores by period

Summary

The periods include provides comprehensive timing information for all match periods including first half, second half, extra time, and penalties. With fields for current minutes/seconds, injury time, and active status, it enables accurate live match timers, period-based analysis, and match state management. Use currentPeriod for live matches when you only need the active period data.