Welcome to Goalise Football API v3

Goalise provides reliable football data tailored for developers who need live, historical, and prediction insights for football matches across leagues worldwide.

v3 is the current version. Where v2 answered with bare foreign keys — home_team_id, league_id, venue_id — and left the client to resolve each one, v3 embeds the entity itself, so a screen is usually one request. v2 is frozen but untouched and keeps working; see the v2 docs if you are still on it.

🧩 What to do with Goalise?

Retrieve live match scores, events, odds and statistics.
Access team and player statistics, including form and goals.
Fetch league standings, top scorers, and matches by season.
Use advanced prediction endpoints for future matches.
Filter data by league, team, season, or match ID.
Resolve team, league and player names into the IDs the other endpoints need.
Check your remaining request allowance without spending a call.
For more things you can do, see API Reference section.

🚀 Quick Start

To start using the Goalise API:

Subscribe to a pricing plan
Choose your plan and billing period at Goalise Checkout.
Get Your API Key
Once subscribed, your API key will be available under your Dashboard.
Make Your First Request

Here's an example using curl:

curl -X GET "https://api.goalise.com/api/v3/matches?league_id=618&season=2024" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

📦 Response Envelope

Every answer — success or failure — comes back in the same shape:

{
  "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": []
}

response holds the payload — an object for single-entity endpoints, an array for lists.
pagination is null unless the endpoint returns a list.
errors is null unless status is error.
meta carries envelope-level information. New keys may be added here without notice, so ignore the ones you do not know.

🔎 Detail Levels and `expand`

An entity comes back at one of three sizes. A reference (id, name, logo) is what you get for an entity mentioned inside another one. A card adds the country and one or two headline fields. The full object is what the entity's own endpoint returns. Nesting never goes deeper than two levels: a team carries its country, that country does not carry its leagues back.

Raise a relation to its full object with ?expand=, comma separated, at most 5 paths, at most one dot per path:

curl -X GET "https://api.goalise.com/api/v3/match?id=1035037&expand=events,lineup" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Each endpoint documents the paths it accepts; anything else is a 400 with code expand.unknown. meta.expanded echoes back what was honoured, so you can tell a relation you asked for from one you did not.

📄 Pagination

?page= is 1-based and page size is fixed per endpoint — there is no cursor. Read pagination.page_count to know when to stop.

⚠️ Errors

Branch on errors[].code, never on the message text.

Code	Meaning
`validation.required`	A required parameter was missing
`validation.invalid`	A parameter was present but not usable
`expand.unknown`	The endpoint does not accept that `expand` path
`expand.too_deep`	More than one dot in an `expand` path
`expand.too_many`	More than 5 `expand` paths
`auth.required`	No bearer token was sent
`auth.invalid`	The token was rejected
`rate_limit.exceeded`	The allowance for a window ran out
`not_found`	Nothing matched the identifiers given
`internal`	Something failed on our side

🔑 Auth and Rate Limits

Every endpoint needs Authorization: Bearer <token>, with the single exception of GET /country-coverage.

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

GET /quota -> returns the same numbers without spending a call.

🗂️ 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. Keep the tag and send it back as If-None-Match: while the answer has not changed the reply is a 304 with no body.

Nothing whose answer moves under a reader carries one, so a fixture list, a live price or a prediction is always fetched in full.

🌍 Language and Time

Responses are in English. Dates are rendered in UTC unless a request asks for a zone with ?timezone= (an IANA name such as Europe/Madrid); the companion timestamp fields are always UTC unix seconds.

📚 API Reference

A quick overview of available API endpoint groups:

🔍 Search

Resolve a team, league or player name into the ID that the other endpoints expect. Results come back ordered by relevance, exact matches first.

Code	Description
TBD	Scheduled but date and time are not known
NS	Match is scheduled and has not started
1H	First half is in progress
HT	Match is at halftime
2H	Second half is in progress
ET	Extra time is being played
BT	Break during extra time
P	Penalty shootout is in progress
SUSP	Suspended by referee's decision, may be rescheduled
INT	Match interrupted temporarily, should resume shortly
FT	Match finished in regular time
AET	Match finished after extra time
PEN	Match finished after penalties
PST	Postponed to a later date
CANC	Cancelled and will not be played
ABD	Abandoned before completion (e.g., weather, safety)
AWD	Technical loss awarded (not played)
WO	WalkOver - opponent forfeited
LIVE	In progress but detailed timing not available

Welcome to Goalise Football API v3

🧩 What to do with Goalise?

🚀 Quick Start

📦 Response Envelope

🔎 Detail Levels and expand

📄 Pagination

⚠️ Errors

🔑 Auth and Rate Limits

🗂️ Conditional Requests

🌍 Language and Time

📚 API Reference

🔍 Search

🌍 Countries

🏆 Leagues

🏟️ Teams

🧑‍💼 Coaches

👤 Players

📅 Matches

Match Status Codes

📊 Standings

⚽ Events

📈 Statistics

🔁 Transfers

🩹 Injuries

🧠 Predictions

🎯 Odds

📹 Video Highlights

🏅 Top Scorers

🗓️ Seasons

🌐 Coverage

📰 News

🏟️ Venues

🛠️ Service

🔀 Migrating from v2

💡 Tips

🔎 Detail Levels and `expand`