Periods

What does the include do?

The periods include allows you to retrieve detailed information about different periods within a football match, including regular time, extra time, and penalties. This include provides 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

Requesting periods

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

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

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

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

Response structure

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

{
  "data": {
    "id": 19439347,
    "sport_id": 1,
    "league_id": 564,
    "season_id": 25659,
    "stage_id": 77476930,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 373219,
    "state_id": 5,
    "venue_id": 2020,
    "name": "Real Madrid vs FC Barcelona",
    "starting_at": "2025-10-26 15:15:00",
    "result_info": "Real Madrid won after full-time.",
    "leg": "1\/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "has_odds": true,
    "has_premium_odds": true,
    "starting_at_timestamp": 1761491700,
    "periods": [
      {
        "id": 6330171,
        "fixture_id": 19439347,
        "type_id": 1,
        "started": 1761491882,
        "ended": 1761494952,
        "counts_from": 0,
        "ticking": false,
        "sort_order": 1,
        "description": "1st-half",
        "time_added": 6,
        "period_length": 45,
        "minutes": 51,
        "seconds": 10,
        "has_timer": false
      },
      {
        "id": 6330453,
        "fixture_id": 19439347,
        "type_id": 2,
        "started": 1761495960,
        "ended": 1761499312,
        "counts_from": 45,
        "ticking": false,
        "sort_order": 2,
        "description": "2nd-half",
        "time_added": 10,
        "period_length": 45,
        "minutes": 100,
        "seconds": 52,
        "has_timer": false
      }
    ]
  }
}

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
1	First Half (1ST_HALF)	0	45
2	Second Half (2ND_HALF)	45	45
3	Extra Time - First Half	90	15
4	Extra Time - Second Half	105	15
5	Penalty Shootout	120	Variable
14	Awaiting Extra Time	90	0
16	Extra Time Halftime	105	0
18	Awaiting Penalties	120	0

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 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 has ended

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['type_id'] in [3, 4] for p in periods)

def has_penalties(periods):
    """Check if match went to penalties"""
    return any(p['type_id'] == 5 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 => [3, 4].includes(p.type_id));
}

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'] in [3, 4]:
        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.