> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods.md). # 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: ```http // Returns Extra Time as a single period https://api.sportmonks.com/v3/football/fixtures/ ?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/ ?api_token=YOUR_TOKEN&include=detailedPeriods ``` **Example:** Get periods for Real Madrid vs FC Barcelona (fixture ID: 19439347) ```http // 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 {% tabs %} {% tab title="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: ```json { "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 } ] } } ``` {% endtab %} {% tab title="Using the detailedPeriods include" %} When you include `detailedPeriods` in your request, you'll receive an array of period objects for each match period. Extra time is returned as two period objects, one for each half: ```json { "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, "detailedperiods": [ { "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": 7000098, "fixture_id": 19606957, "type_id": 5314, "started": 1782772425, "ended": 1782773624, "counts_from": 90, "ticking": false, "sort_order": 3, "description": "extra-time-1st-half", "time_added": 5, "period_length": 15, "minutes": 109, "seconds": 59, "has_timer": false }, { "id": 7000101, "fixture_id": 19606957, "type_id": 39, "started": 1782773720, "ended": 1782774772, "counts_from": 105, "ticking": false, "sort_order": 4, "description": "extra-time-2nd-half", "time_added": 2, "period_length": 15, "minutes": 122, "seconds": 32, "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 }, ] } } ``` {% endtab %} {% endtabs %} ### Field descriptions
FieldTypeDescription
idintegerUnique identifier for this period
fixture_idintegerID of the fixture this period belongs to
type_idintegerType identifier for the period (see Period Types below)
startedintegerUNIX timestamp of when the period started
endedinteger/nullUNIX timestamp of when the period ended (null if ongoing)
counts_fromintegerMinute from which this period starts counting (e.g., 0 for 1st half, 45 for 2nd half)
tickingbooleanWhether the period is currently active/being played
sort_orderintegerSorting order of the period (1 = first, 2 = second, etc.)
descriptionstringHuman-readable description of the period
time_addedinteger/nullAdditional injury/stoppage time added to the period (in minutes)
period_lengthintegerStandard length of the period in minutes (usually 45 for regular time)
minutesintegerCurrent minute within the match (cumulative)
secondsintegerSeconds after the current minute (0-59)
has_timerbooleanWhether 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: ```http 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: ```http 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: ```http https://api.sportmonks.com/v3/football/fixtures/{fixture_id} ?api_token=YOUR_TOKEN&include=periods.events ``` #### periods.statistics Get statistics specific to this period: ```http https://api.sportmonks.com/v3/football/fixtures/{fixture_id} ?api_token=YOUR_TOKEN&include=periods.statistics ``` ### Code examples {% tabs %} {% tab title="JavaScript" %} ```javascript // 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 = `
${period.description}
${period.minutes}:${String(period.seconds).padStart(2, '0')}
${period.time_added ? `
+${period.time_added} min
` : ''}
🔴 LIVE
`; 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 = `
${period.description}
${period.counts_from}-${period.counts_from + period.period_length}'
${period.time_added ? `
+${period.time_added}'
` : ''} `; 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(); ``` {% endtab %} {% tab title="Python" %} ```python 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") ``` {% endtab %} {% tab title="PHP" %} ```php $apiToken, "include" => "periods" ]); $response = file_get_contents("{$url}?{$params}"); $data = json_decode($response, true); // Extract periods $periods = $data["data"]["periods"] ?? []; // Display all periods foreach ($periods as $period) { echo "\n{$period['description']}:\n"; echo " Started: " . date("Y-m-d H:i:s", $period["started"]) . "\n"; if (!empty($period["ended"])) { echo " Ended: " . date("Y-m-d H:i:s", $period["ended"]) . "\n"; $duration = $period["ended"] - $period["started"]; echo " Duration: " . floor($duration / 60) . " minutes\n"; } echo " Ticking: " . ($period["ticking"] ? "true" : "false") . "\n"; if (!empty($period["time_added"])) { echo " Injury time: +{$period['time_added']} minutes\n"; } } // Find current/active period function getCurrentPeriod(array $periods): ?array { foreach ($periods as $period) { if (!empty($period["ticking"])) { return $period; } } return null; } $current = getCurrentPeriod($periods); if ($current) { echo "\nLIVE: Currently in {$current['description']}\n"; echo "Match time: {$current['minutes']}:" . str_pad($current["seconds"], 2, "0", STR_PAD_LEFT) . "\n"; } else { echo "\nMatch ended or not started\n"; } // Calculate total match time function calculateTotalTime(array $periods): int { $totalMinutes = 0; foreach ($periods as $period) { if (!empty($period["ended"])) { $durationSeconds = $period["ended"] - $period["started"]; $totalMinutes += floor($durationSeconds / 60); } } return $totalMinutes; } $totalTime = calculateTotalTime($periods); echo "\nTotal playing time: {$totalTime} minutes\n"; // Track injury time patterns function analyzeInjuryTime(array $periods): array { $injuryTime = []; foreach ($periods as $period) { if (!empty($period["time_added"])) { $injuryTime[$period["description"]] = $period["time_added"]; } } return $injuryTime; } $injuryAnalysis = analyzeInjuryTime($periods); echo "\nInjury time analysis:\n"; foreach ($injuryAnalysis as $periodName => $minutes) { echo " {$periodName}: +{$minutes} minutes\n"; } // Check if match went to extra time function hasExtraTime(array $periods): bool { foreach ($periods as $period) { if ($period["description"] === "extra-time") { return true; } } return false; } function hasPenalties(array $periods): bool { foreach ($periods as $period) { if ($period["description"] === "penalties") { return true; } } return false; } if (hasExtraTime($periods)) { echo "\nMatch included extra time\n"; } if (hasPenalties($periods)) { echo "Match decided by penalties\n"; } ``` {% endtab %} {% endtabs %} ### Common use cases #### 1. Live match timer display Display accurate live match time with injury time: ```python 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: ```python 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: ```python 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**](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/includes/events) - Cross-reference events with periods to show when they occurred * [**Statistics**](https://docs.sportmonks.com/football/definitions/types/statistics) - Get period-specific statistics * [**States**](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/includes/states) - Understand match state transitions * [**Scores**](https://docs.sportmonks.com/football/tutorials-and-guides/tutorials/includes/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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes/periods.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.