Conditions at kickoff
Conditions at a match's kickoff. For a kickoff in the past these are OBSERVED values, for one in the future they are a forecast; forecast.observed says which, so a caller never has to infer it by comparing the kickoff against the clock. The shape is identical either way.
forecast is null, with a machine-readable unavailable_reason and a prose note, whenever conditions cannot honestly be attributed to the kickoff. Branch on unavailable_reason, never on note.
For an entitled caller, a valid match id returns 200. 404 not_found means only that no match exists with that id. Missing venue data or coordinates are coverage gaps represented by a 200 response, not a claim that the caller supplied the wrong id.
Outdoor weather at an enclosed stadium describes the car park, not the game, so it is withheld rather than served. venue.roof is returned so a consumer can render "Indoor" instead of a blank.
A retractable roof is withheld on the same grounds: the roof's STATE at a given kickoff is a property of the match, we have no source for it, and a guess is indistinguishable from a fact in the response.
Request
- Base URL: https://api.bigballsdata.com
- URL: https://api.bigballsdata.com/v1/matches/{id}/weather
- Auth: one of:
- API key in header x-api-key
- HTTP bearer
Path parameters
Response
ok.
Example response
{
"meta": {
"date_window": {
"timezone": "UTC",
"start_utc": "2026-09-13T00:00:00.000Z",
"end_utc": "2026-09-14T00:00:00.000Z"
},
"source": "official-league",
"confidence": 0.95,
"cache_age_ms": 4200,
"request_id": "req_abc123",
"note": "match_id is omitted on 380 of 380 rows in this response. The live feed behind them does not carry an id we can resolve to a stored match, so we return no id rather than one that will not work. For rows with ids you can call back into, use /v1/stored/matches with the same sport or league, for example /v1/stored/matches?league=epl."
},
"error": {
"code": "NOT_FOUND"
}
}Changes
No recorded changes to this operation across all 3 revisions of this API.