# Order a Football Timeline with Stoppage Time

Football timeline events can contain minute and minute_extra values. A label such as 45+2 is not the same representation as an ordinary forty-seventh minute, even when a display chooses to position them near each other. Retain both fields and format the clock explicitly. Null minutes need an unknown-time state rather than a guessed position at kickoff.

By Stats API Editorial (AI-assisted) · Reviewed by Codex automated editorial review · Published 2026-10-26 · Last reviewed 2026-10-11

Canonical URL: https://stats-api.com/blog/football-match-timeline-stoppage-time-order

## Preserve the event clock you receive

Football timeline events can contain minute and minute_extra values. A label such as 45+2 is not the same representation as an ordinary forty-seventh minute, even when a display chooses to position them near each other. Retain both fields and format the clock explicitly. Null minutes need an unknown-time state rather than a guessed position at kickoff.

The timeline response also carries type, detail, comments and nullable team, player and related_player objects. Treat these as observed event attributes. The schema does not promise a unique public event identifier, so avoid building a permanent event identity from a display label alone.

## Use a documented display ordering policy

The example sorts by the base minute, then extra minute, retaining original order for equal clocks. Unknown minutes appear last. This is a display policy for the returned observations, not a reconstruction of exact event order. Two incidents at the same minute may have no finer precision in the contract.

Do not collapse an event to minute plus minute_extra and discard the original fields. Keeping them lets your interface display 45+2 and 90+4 faithfully. It also helps a reviewer see where ordering is a rendering choice rather than a fact about the exact second an incident happened.

## Run the reproducible example

This Python 3 example uses deliberately synthetic inputs, not a downloaded match or a forecast for a real fixture. Save it as example.py and run python3 example.py. It uses only the standard library and its assertions check the behavior discussed here. Replace the fixture inputs with validated API records when connecting your application; demo identifiers are not production lookup values.

**Complete offline example**

```python
def label(event):
    if event["minute"] is None:
        return "time unknown"
    extra = event["minute_extra"]
    return str(event["minute"]) + (f"+{extra}" if extra else "")

def ordered(events):
    return sorted(enumerate(events),key=lambda pair:(
        pair[1]["minute"] is None,
        pair[1]["minute"] if pair[1]["minute"] is not None else 0,
        pair[1]["minute_extra"] or 0,pair[0]))

events = [{"minute":90,"minute_extra":4,"type":"goal"},
          {"minute":45,"minute_extra":2,"type":"card"},
          {"minute":None,"minute_extra":None,"type":"other"},
          {"minute":45,"minute_extra":2,"type":"substitution"}]
result = [event for _,event in ordered(events)]
assert [label(e) for e in result] == ["45+2","45+2","90+4","time unknown"]
assert result[0]["type"] == "card" and result[1]["type"] == "substitution"
print([label(e) for e in result])
```

## Read the result

The output preserves both 45+2 labels in their original relative order, followed by 90+4 and the unknown-time event. That is deterministic rendering without claiming precision beyond the supplied fields.

## Separate snapshots from notification events

Polling a timeline returns a snapshot of known incidents. Re-reading the same snapshot must not send every goal notification again. If your application creates notifications, define a deduplication and correction policy based on retained snapshots and the fields available, and accept that ambiguous changes may require review.

A changed detail or player attribution can be a correction to an existing incident rather than a new event. Without a documented stable event ID, blindly appending every changed row risks duplicate stories. For a simple match page, replacing the displayed snapshot is often safer than pretending to maintain a complete event stream.

## Design for partial and polled observations

Check coverage.timeline_available and keep an empty event list distinct from unsupported coverage or a failed request. The live timeline operation is polled data; a short cache duration does not establish sub-minute source latency. Display retrieval information honestly and do not promise instant incident delivery.

Test equal minutes, stoppage time, unknown minutes, null player objects and corrected descriptions. A timeline card should remain readable without a player name or team image. The central goal is a faithful view of returned events, with your sorting and formatting choices visible rather than hidden as invented precision.

## Connect this to your project

Use the timeline endpoint to build a replaceable match snapshot first. Add notification behavior only after testing duplicate and correction handling against retained responses. The cache-aware integration guide helps keep repeated reads controlled while the contract defines the fields you may display.

- [Read the API contract](https://stats-api.com/docs)
- [Explore football API capabilities](https://stats-api.com/football-api)
- [Plan controlled cached reads](https://stats-api.com/blog/cache-aware-football-agents)