Changelog

What has changed in the Goalise API, newest first. Breaking changes are called out as such — everything else is additive and safe to ignore until you need it.

This page covers v3. v2 is frozen and only receives data, not contract changes.

2026-09-13

?timezone= is accepted on more endpoints. It now works on /match-events, /match-statistics, /match-lineup, /predictions, /highlights, /player-match-statistics, /odds and /live-odds, alongside the endpoints that already took it. As everywhere else, it only changes how the rendered date strings are written — the companion timestamp fields stay UTC unix seconds.

v3.0.0 — Goalise API v3

The first release of v3. v2 answered with bare foreign keys — home_team_id, league_id, venue_id — and left the client to resolve each one, so a single screen cost several calls. v3 embeds the entity instead.

Responses

Every entity arrives embedded. A fixture carries both teams and its venue as objects, an absence carries the player, club, competition and fixture, a prediction carries every team it names. Squad and fixture screens that used to cost a fan-out of follow-up calls are now one request.

One envelope for every answer, success or failure:

{
  "status": "success",
  "pagination": { "total_count": 351, "page_size": 120, "page_count": 3, "current_page": 1 },
  "errors": null,
  "meta": { "api_version": "3.0.0", "generated_at": 1757721600, "expanded": ["venue"] },
  "response": []
}

Read the payload from response. pagination is null unless the endpoint returns a list; errors is null unless status is error.

Three detail levels. An entity mentioned inside another one comes back as a reference (id, name, logo). A card adds the country and a headline field or two. The full object is what the entity's own endpoint returns. Nesting stops at two levels: a team carries its country, that country does not carry its leagues back.

Machine-readable errors. Branch on errors[].code — validation.required, validation.invalid, expand.unknown, expand.too_deep, expand.too_many, auth.required, auth.invalid, rate_limit.exceeded, not_found, internal — instead of matching message text.

Requests

?expand= raises a relation from a reference to its full object. Comma separated, at most 5 paths, at most one dot per path. Each endpoint documents what it accepts; anything else is a 400 with expand.unknown. meta.expanded echoes back what was honoured.

Pagination is explicit. ?page= is 1-based, page size is fixed per endpoint, and there is no cursor. /head-to-head, /highlights, /odds and /player-statistics are paginated in v3 and were not in v2 — a long rivalry or a full squad now arrives in pages rather than one oversized payload.

Conditional requests. The dictionary endpoints — /countries, /venues, /league-seasons, /league-rounds, /bookmakers, /bets, /live-bets, /country-coverage — answer with an ETag and a Cache-Control. Send the tag back as If-None-Match and you get a 304 with no body while nothing has changed. Anything that moves under a reader — a fixture list, a live price, a prediction — deliberately carries no tag.

?timezone= renders date strings in an IANA zone. timestamp fields are always UTC unix seconds regardless.

Breaking — id_list is now ids, comma separated. The old dash-separated id_list still works on /matches.

Breaking — required parameters moved. season is now required on /league-standing and optional on /team-statistics.

New endpoints

Endpoint	What it does
`GET /quota`	What is left of your allowance per minute, hour and day — without spending a call
`GET /logs`	Your own token's recent requests, newest first, capped at 200
`GET /country-coverage`	Every country with at least one published competition, and what is covered in it. The only endpoint that takes no token

Rate limits

Every response carries X-Rate-Limit-Limit, X-Rate-Limit-Remaining and X-Rate-Limit-Reset for whichever window is closest to its ceiling, plus X-Rate-Limit-<window> / X-Rate-Remaining-<window> / X-Rate-Reset-<window> for minute, hour and day separately. Reset values are unix seconds. Going over returns 429 with rate_limit.exceeded and a Retry-After.

Moved and renamed

Breaking for deep links — endpoint groups were reorganised. Highlights and Injuries are their own groups now, /predictions moved under Matches, and /quota and /logs live in a new Service group. The tag Injures was renamed to Injuries.

Full detail is in the v3 API reference, and Migrating from v2 is the short version.