An observation is not a medical forecast
An injury or suspension feed can support a football availability screen, but the response must be read within its documented meaning. Stats API injury records include player, team, season, type, reason and observed_at. The schema does not provide a promised return date or a universal fit-to-play boolean. Do not derive either from a reason string.
This article concerns software representation of sporting observations, not medical advice. Keep the returned description as attributed data and avoid adding a diagnosis, severity or expected recovery period. The useful application behavior is to show what was observed, for whom and when.
Keep time and context visible
Display the player and team identity, season context and observed_at alongside the reason when present. Store your own retrieval time separately. A recently retrieved response can contain an older observation, so “checked just now” must not be phrased as “injured just now.”
The example calculates the age of a synthetic observation at a fixed evaluation instant. It rejects a future timestamp rather than silently reporting a negative age. The age is a display aid, not a rule that determines whether the player has recovered or whether a suspension still applies.
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.
from datetime import datetime
def observed_age_hours(record, now):
stamp = datetime.fromisoformat(record["observed_at"].replace("Z","+00:00"))
clock = datetime.fromisoformat(now.replace("Z","+00:00"))
if stamp.tzinfo is None or clock.tzinfo is None:
raise ValueError("timezone required")
age = (clock-stamp).total_seconds()/3600
if age < 0:
raise ValueError("future observation")
return age
record = {"player":{"id":"player_demo"},"team":{"id":"team_demo"},
"season":{"id":"season_demo"},"reason":None,"type":"injury",
"observed_at":"2026-10-01T12:00:00Z"}
age = observed_age_hours(record,"2026-10-02T00:00:00Z")
assert age == 12
assert record["reason"] is None
assert "return_date" not in record
try:
observed_age_hours(record,"2026-10-01T11:00:00Z")
except ValueError:
pass
else:
raise AssertionError("future timestamp accepted")
print({"observation_age_hours":age,"reason":record["reason"]})
Read the result
The synthetic record is twelve hours old at the fixed test instant, and its unknown reason remains null. No return date is generated. The future-observation test fails explicitly instead of producing a misleading age.
Absence does not prove availability
An empty injuries response should be shown as no observations returned for the selected context. It does not prove that every player is fit, eligible or likely to start. Coverage, publication timing and data gaps can all affect what appears. A lineup response, a squad response and an injury observation have different purposes and should not be collapsed into one boolean.
If a fantasy application needs an availability decision, define the evidence and review policy explicitly. Keep any application decision separate from the source record, and show uncertainty when the required inputs are missing. Do not turn null reason or type values into reassuring labels such as healthy.
Avoid stale alerts and duplicate stories
When refreshing a team view, join records by the documented player, team and season context and compare the observed values before generating a new notification. The contract does not expose a universal injury event ID, so a deduplication key is your application policy and needs collision tests. Two observations about the same player may refer to different contexts.
Test null reasons, multiple seasons, old observations and empty lists. If your UI applies an age warning, label it as your display threshold and make the timestamp available. A careful observation screen is more useful than a confident availability badge built from assumptions.
Connect this to your project
Inspect representative injury responses for your intended teams before designing availability labels. Use the current contract for fields and the time-awareness guide for timestamp semantics. Keep your product's decisions traceable to the observations it actually received.