AET
| Finished After Extra Time | The match has ended after 120 minutes. | | 8 | FT\_PEN | Full-Time After Penalties | The match finished following a penalty shootout. | | 9 | INPLAY\_PENALTIES | Penalty Shootout | Penalties are being taken to decide the winner. | | 10 | POSTPONED | Postponed | The match has been postponed to another date. | | 11 | SUSPENDED | Suspended | The match is suspended and will continue later. | | 12 | CANCELLED | Cancelled | The match has been permanently cancelled. | | 13 | TBA | To Be Announced | Fixture has no confirmed date/time yet. | | 14 | WO | Walk Over | A victory was awarded because no opponent was available. | | 15 | ABANDONED | Abandoned | The match was abandoned and will resume later. | | 16 | DELAYED | Delayed | Kick-off has been delayed. | | 17 | AWARDED | Awarded | Winner decided externally (administrative decision). | | 18 | INTERRUPTED | Interrupted | Temporarily stopped (e.g., bad weather). | | 19 | AU | Awaiting Updates | Temporary state due to data or connectivity delay. | | 20 | DELETED | Deleted | The fixture is no longer active in standard calls but can still be fetched with `deleted=1`. | | 21 | EXTRA\_TIME\_BREAK | Extra Time Break | Short break between extra time halves. | | 22 | INPLAY\_2ND\_HALF | 2nd Half | The game is in play (second half). | | 25 | PEN\_BREAK | Penalties Break | Waiting for penalties to start. | | 26 | PENDING | Pending | The fixture awaits new data or verification. | ### State transitions and flow Understanding how states transition is crucial for building robust applications: #### Normal match flow ``` NS (Not Started) ↓ Match starts LIVE (1st Half) ↓ Half-time whistle HT (Half Time) ↓ 2nd half starts LIVE (2nd Half) ↓ Full-time whistle FT (Full Time) ``` | From | To | Trigger | Description | | ---- | ---- | ----------------- | -------------------------------- | | NS | LIVE | Match starts | Game begins (1st half) | | LIVE | HT | Half-time whistle | Match reaches half-time break | | HT | LIVE | 2nd half starts | Second half commences | | LIVE | FT | Full-time whistle | Match concludes after 90 minutes | #### Match with extra time ``` FT (After 90 minutes) ↓ Extra time starts ET (Extra Time 1st Half) ↓ Break BREAK (Extra Time Half Time) ↓ Extra time 2nd half ET (Extra Time 2nd Half) ↓ Finished AET (After Extra Time) ``` | From | To | Trigger | Description | | ----- | ----- | --------------------------- | ------------------------------- | | FT | ET | Extra time starts | Game continues after full-time | | ET | BREAK | 1st half of extra time ends | Extra time break/half-time | | BREAK | ET | Extra time 2nd half starts | Second half of extra time | | ET | AET | Extra time concludes | Match finished after extra time | #### Match with penalties ``` AET (After Extra Time) ↓ Penalties start PEN_LIVE (Penalty Shootout) ↓ Shootout complete FT_PEN (Finished on Penalties) ``` | From | To | Trigger | Description | | --------- | --------- | ----------------- | -------------------------- | | AET | PEN\_LIVE | Penalties start | Penalty shootout begins | | PEN\_LIVE | FT\_PEN | Shootout complete | Match decided by penalties | #### Problem states ``` NS (Not Started) ↓ Issues arise DELAYED → (eventually) → LIVE or POSTP POSTP → (rescheduled) → NS CANCL → (no transition, final state) LIVE (During match) ↓ Issues arise INT (Interrupted) → (may resume) → LIVE SUSP (Suspended) → (may resume) → LIVE ABAN (Abandoned) → (no transition, final state) ``` | From | To | Trigger | Description | | ------- | ------- | ------------------- | ---------------------------------------- | | NS | DELAYED | Issues arise | Match start delayed | | DELAYED | LIVE | Delay resolved | Match eventually starts | | DELAYED | POSTP | Cannot resume | Match postponed to another date | | POSTP | NS | Rescheduled | Match rescheduled for later date | | NS | CANCL | Match cancelled | Final state - no further transitions | | LIVE | INT | Issues during match | Match interrupted (weather, crowd, etc.) | | INT | LIVE | Issues resolved | Match resumes | | LIVE | SUSP | Match suspended | Match temporarily suspended | | SUSP | LIVE | Suspension lifted | Match resumes after suspension | | LIVE | ABAN | Match abandoned | Final state - match abandoned | ### Filtering by state To filter fixtures based on specific states, use the `filters` parameter: ``` https://api.sportmonks.com/v3/football/fixtures ?api_token=YOUR_TOKEN&include=state&filters=fixtureStates:2 ``` Filter for multiple states: ``` https://api.sportmonks.com/v3/football/fixtures ?api_token=YOUR_TOKEN&include=state&filters=fixtureStates:2,3,10 ``` #### Common Filter Scenarios **Get only live matches:** ``` &filters=fixtureStates:2,10,7 ``` States: INPLAY\_1ST\_HALF (2), INPLAY\_2ND\_HALF (22), INPLAY\_ET (6), PEN\_LIVE (7) **Get finished matches:** ``` &filters=fixtureStates:5,6,8 ``` States: FT (5), AET (7), FT\_PEN (8) **Get problem matches:** ``` &filters=fixtureStates:12,13,14,15,16,17 ``` States: CANCELLED (12), ABANDONED (15), DELAYED (16), AWARDED (17), INTERRUPTED (18) ### Nested includes #### state.type Get detailed type information for the state: ``` https://api.sportmonks.com/v3/football/fixtures/{fixture_id} ?api_token=YOUR_TOKEN&include=state.type ``` This returns additional type metadata (though state itself is typically sufficient). ### Code examples #### Python example ```python import requests # API configuration API_TOKEN = "YOUR_TOKEN" # Get all live fixtures def get_live_fixtures(): """Get all currently live matches""" url = "https://api.sportmonks.com/v3/football/fixtures" params = { "api_token": API_TOKEN, "include": "state,participants", "filters": "fixtureStates:2,6,7,22" # INPLAY_1ST_HALF, INPLAY_2ND_HALF, INPLAY_ET, PEN_LIVE } response = requests.get(url, params=params) data = response.json() fixtures = data.get('data', []) print(f"🔴 {len(fixtures)} live matches found:\n") for fixture in fixtures: state = fixture.get('state', {}) print(f"{fixture['name']}") print(f" Status: {state['name']} ({state['state']})") print() return fixtures # Check specific fixture state def check_fixture_state(fixture_id): """Check the state of a specific fixture""" url = f"https://api.sportmonks.com/v3/football/fixtures/{fixture_id}" params = { "api_token": API_TOKEN, "include": "state" } response = requests.get(url, params=params) data = response.json() fixture = data['data'] state = fixture.get('state', {}) return { 'fixture_id': fixture_id, 'fixture_name': fixture['name'], 'state_id': state['id'], 'state_code': state['state'], 'state_name': state['name'], 'is_live': state['id'] in [2, 6, 7, 22], 'is_finished': state['id'] in [5, 7, 8], 'has_problem': state['id'] in [12, 15, 16, 17, 18] } # Monitor state changes def monitor_fixtures(fixture_ids, callback): """Monitor fixtures for state changes""" previous_states = {} url = "https://api.sportmonks.com/v3/football/fixtures/multi/" + ",".join(map(str, fixture_ids)) params = { "api_token": API_TOKEN, "include": "state" } response = requests.get(url, params=params) data = response.json() for fixture in data.get('data', []): fixture_id = fixture['id'] current_state = fixture['state']['id'] if fixture_id in previous_states: if previous_states[fixture_id] != current_state: # State changed! callback(fixture, previous_states[fixture_id], current_state) previous_states[fixture_id] = current_state # Get fixtures with problems def get_problem_fixtures(): """Get all postponed, cancelled, or problematic fixtures""" url = "https://api.sportmonks.com/v3/football/fixtures" params = { "api_token": API_TOKEN, "include": "state,participants", "filters": "fixtureStates:12;15;16;17;18" # Problem states } response = requests.get(url, params=params) data = response.json() fixtures = data.get('data', []) # Group by state type by_state = {} for fixture in fixtures: state_name = fixture['state']['name'] if state_name not in by_state: by_state[state_name] = [] by_state[state_name].append(fixture) print("⚠️ Problem Fixtures:\n") for state_name, matches in by_state.items(): print(f"{state_name}: {len(matches)} matches") for match in matches: print(f" - {match['name']}") print() return by_state # Categorise fixtures by state def categorise_fixtures_by_state(fixtures): """Categorise fixtures into groups based on state""" categories = { 'upcoming': [], 'live': [], 'finished': [], 'postponed': [], 'cancelled': [], 'other': [] } for fixture in fixtures: state_id = fixture['state']['id'] if state_id == 1: # Not Started categories['upcoming'].append(fixture) elif state_id in [2, 6, 7, 22]: # INPLAY_1ST_HALF, INPLAY_2ND_HALF, INPLAY_ET, PEN_LIVE categories['live'].append(fixture) elif state_id in [5, 7, 8]: # FT, AET, FT_PEN categories['finished'].append(fixture) elif state_id == 10: # Postponed categories['postponed'].append(fixture) elif state_id == 12: # Cancelled categories['cancelled'].append(fixture) else: categories['other'].append(fixture) return categories # Example usage live_matches = get_live_fixtures() fixture_state = check_fixture_state(18535517) print(f"Fixture state: {fixture_state}") problem_fixtures = get_problem_fixtures() ``` #### JavaScript Example ```javascript // API configuration const API_TOKEN = "YOUR_TOKEN"; // Get all live fixtures async function getLiveFixtures() { const url = "https://api.sportmonks.com/v3/football/fixtures"; const params = new URLSearchParams({ api_token: API_TOKEN, include: "state,participants", filters: "fixtureStates:2,10,7" // LIVE, ET, PEN_LIVE }); try { const response = await fetch(`${url}?${params}`); const data = await response.json(); const fixtures = data.data || []; console.log(`🔴 ${fixtures.length} live matches found:\n`); fixtures.forEach(fixture => { const state = fixture.state || {}; console.log(`${fixture.name}`); console.log(` Status: ${state.name} (${state.state})`); console.log(); }); return fixtures; } catch (error) { console.error("Error fetching live fixtures:", error); return []; } } // Check specific fixture state async function checkFixtureState(fixtureId) { const url = `https://api.sportmonks.com/v3/football/fixtures/${fixtureId}`; const params = new URLSearchParams({ api_token: API_TOKEN, include: "state" }); try { const response = await fetch(`${url}?${params}`); const data = await response.json(); const fixture = data.data; const state = fixture.state || {}; return { fixture_id: fixtureId, fixture_name: fixture.name, state_id: state.id, state_code: state.state, state_name: state.name, is_live: [2, 6, 7, 22].includes(state.id), is_finished: [5, 7, 8].includes(state.id), has_problem: [12, 15, 16, 17, 18].includes(state.id) }; } catch (error) { console.error("Error checking fixture state:", error); return null; } } // Display state badge function createStateBadge(state) { const badge = document.createElement('span'); badge.className = `state-badge state-${state.state.toLowerCase()}`; // Color coding const colors = { 'LIVE': '#ff0000', 'FT': '#28a745', 'HT': '#ffc107', 'POSTP': '#6c757d', 'CANCL': '#dc3545' }; badge.style.backgroundColor = colors[state.state] || '#6c757d'; badge.style.color = 'white'; badge.style.padding = '4px 8px'; badge.style.borderRadius = '4px'; badge.style.fontWeight = 'bold'; badge.textContent = state.short_name; return badge; } // Get fixtures with problems async function getProblemFixtures() { const url = "https://api.sportmonks.com/v3/football/fixtures"; const params = new URLSearchParams({ api_token: API_TOKEN, include: "state,participants", filters: "fixtureStates:12;13;14;15;16;17" // Problem states }); try { const response = await fetch(`${url}?${params}`); const data = await response.json(); const fixtures = data.data || []; // Group by state const byState = {}; fixtures.forEach(fixture => { const stateName = fixture.state.name; if (!byState[stateName]) { byState[stateName] = []; } byState[stateName].push(fixture); }); console.log("⚠️ Problem Fixtures:\n"); Object.entries(byState).forEach(([stateName, matches]) => { console.log(`${stateName}: ${matches.length} matches`); matches.forEach(match => { console.log(` - ${match.name}`); }); console.log(); }); return byState; } catch (error) { console.error("Error fetching problem fixtures:", error); return {}; } } // Categorise fixtures function categoriseFixturesByState(fixtures) { const categories = { upcoming: [], live: [], finished: [], postponed: [], cancelled: [], other: [] }; fixtures.forEach(fixture => { const stateId = fixture.state.id; if (stateId === 1) { categories.upcoming.push(fixture); } else if ([2, 6, 7, 22].includes(stateId)) { categories.live.push(fixture); } else if ([5, 7, 8].includes(stateId)) { categories.finished.push(fixture); } else if (stateId === 10) { categories.postponed.push(fixture); } else if (stateId === 12) { categories.cancelled.push(fixture); } else { categories.other.push(fixture); } }); return categories; } // Build fixtures list with state indicators function buildFixturesList(fixtures) { const container = document.createElement('div'); container.className = 'fixtures-list'; const categories = categoriseFixturesByState(fixtures); // Display by category Object.entries(categories).forEach(([category, matches]) => { if (matches.length > 0) { const section = document.createElement('div'); section.className = 'fixture-category'; section.innerHTML = `