API Documentation

Basics

Base URL

All requests are made to:

Authentication

Send your API key as a Bearer token. Requests without a valid key return401.

curl "https://api.goal-api.com/v1/leagues" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your key from the dashboard and keep it secret — treat it like a password.

Response format

Every response is JSON with a success flag and a data payload; list endpoints add pagination.

{
  "success": true,
  "data": { ... },
  "pagination": { "total": 100, "limit": 50, "offset": 0, "hasMore": true }
}

Countries

Access country data and retrieve leagues associated with specific countries.

Leagues

Get league information, standings, fixtures, teams, and top scorers for any football league.

Teams

Access team data, squad information, fixtures, results, and detailed statistics.

Fixtures

Get match schedules, live scores, lineups, events, statistics, and detailed match information.

Standings

Access league tables, team rankings, home/away standings, and standings grouped by zones.

Players

Search players, get player profiles, statistics, compare players, and view top performers.

Coaches

Get coach information, search coaches, and view coaches by team or country.

Head-to-Head

Get historical matchups and statistics between two teams.

Results

Get completed match results, today's and yesterday's results, and high-scoring matches.

Videos

Access match highlights and video content for matches and leagues.

Odds

Betting odds from multiple bookmakers. Pre-match odds cover 1X2, double chance, both-teams-to-score, Asian handicap, and over/under lines. In-play odds are refreshed every two minutes while a match is running.

Predictions

Outcome probabilities for upcoming matches — home win, draw, away win, double chance, over/under, both teams to score, and Asian handicap. Values are returned as strings between "0.00" and "1.00".

WebSocket (Live Data)

Subscribe to a match and receive live score, event, and statistics updates over a persistent WebSocket connection, instead of polling the REST API.

const res = await fetch("https://api.goal-api.com/v1/ws/token", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` }
});
const { data } = await res.json();
// data.token, data.expiresIn (seconds)

const ws = new WebSocket(`wss://api.goal-api.com/ws?wsToken=${data.token}`);

ws.onopen = () => {
  ws.send(JSON.stringify({ type: "auth", token: data.token }));
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
};

ws.send(JSON.stringify({
  type: "subscribe",
  resource: "match",
  matchId: "12345"
}));

{
  "type": "match_update",
  "data": {
    "match_id": "12345",
    "match_status": "2H",
    "match_hometeam_score": "2",
    "match_awayteam_score": "1",
    "goalscorer": [ ... ],
    "cards": [ ... ]
  },
  "timestamp": 1783040229469
}

{
  "type": "error",
  "success": false,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Invalid or expired token",
    "category": "authentication"
  },
  "timestamp": 1783040229469
}

Webhooks

The counterpart to the WebSocket API. Instead of holding a connection open, you register a URL and we POST to it when a match event happens — a goal, a kick-off, a full-time whistle. This suits serverless functions and backends that cannot keep a socket alive. Manage your endpoints in the dashboard.

Events

Filtering by competition

By default an endpoint receives events from every competition we cover. Set leagueIds to receive only the ones you follow. Filtered-out events are never queued, so they never reach your endpoint and never count against your plan.

# Only these competitions. Ids come from GET /leagues
# (either `id` or `apiId` is accepted), or from
# GET /auth/webhook-endpoints/leagues.

curl -X PATCH https://api.goalapi.io/auth/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $GOAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "leagueIds": ["152", "302", "207"] }'

# An empty array turns the filter off again — every competition, the default.
  -d '{ "leagueIds": [] }'

Managing endpoints

These are normal authenticated REST calls — your API key as a Bearer token, exactly like every other endpoint on this page.

Verifying the signature

// Node.js / Express
import crypto from "crypto";

app.post("/webhooks/goal-api",
  express.raw({ type: "application/json" }),   // the RAW bytes — a re-serialised
  (req, res) => {                              // body will not match the signature
    const header = req.get("X-Goal-Signature");        // t=1736899200,v1=abc123...
    const [t, v1] = header.split(",").map(p => p.split("=")[1]);

    const expected = crypto
      .createHmac("sha256", process.env.GOAL_WEBHOOK_SECRET)
      .update(t + "." + req.body)
      .digest("hex");

    // Constant-time compare: a plain === leaks the correct signature one byte at a
    // time to anyone patient enough to measure how long the comparison took.
    const valid = crypto.timingSafeEqual(
      Buffer.from(v1, "hex"),
      Buffer.from(expected, "hex")
    );
    if (!valid) return res.sendStatus(401);

    // Reject anything older than five minutes, or a captured delivery can be replayed.
    if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(401);

    const event = JSON.parse(req.body);
    console.log(event.event, event.data);   // "goal.scored", { homeTeam, score, ... }

    // Answer 2xx fast. We retry on anything else (1m, 5m, 25m, 2h, 10h), and we time
    // out after 8s — so do the work after responding, not before.
    res.sendStatus(200);
  }
);

Delivery & retries

• Respond 2xx quickly. We time out after 8 seconds, so do your work after responding, not before.
• A non-2xx response is retried with backoff: 1m, 5m, 25m, 2h, 10h.
• An endpoint that fails 20 times in a row is disabled automatically. Fix it and re-enable it from the dashboard.
• Every attempt is logged — status code, duration, error — on the endpoint's page in the dashboard.

Deliveries and your plan quota

A webhook delivery is a request we make on your behalf, and it is metered like one: each delivery attempt counts against the same allowance as your API calls. There is no separate webhook budget. Three consequences worth knowing before you rely on it:

• A retry costs a request each time. An endpoint returning 500 through all five attempts spends five.
• When your allowance runs out, deliveries are dropped, not queued. A goal notification arriving a day late is worse than one that never arrives, so we do not hold them — the event is gone.
• That makes the competition filter the difference between an allowance spent on matches you follow and one spent on the worldwide feed.

GET /auth/webhook-endpoints/:id/stats breaks that spend down by competition and by event, including how much went on retries and how many events were dropped. The same breakdown is on the endpoint's card in the dashboard, where each row is a checkbox that writes your filter.

Testing locally

Deliveries are sent from our servers, so they cannot reach localhost or a private address — your machine is not on the public internet, and those URLs are rejected. Expose your local endpoint with a tunnel and register the public URL it gives you:

# ngrok
ngrok http 3000
# -> https://abc123.ngrok-free.app  (register this as your webhook URL)

# or cloudflared
cloudflared tunnel --url http://localhost:3000

Then hit Send test next to your endpoint in the dashboard to fire a signed sample event immediately — no need to wait for a live match.