### GET /standings/:leagueId/zones

Source: https://goal-api.com/documentation

Get the promotion and relegation zones for a league standings.

```APIDOC
## GET /standings/:leagueId/zones

### Description
Get promotion/relegation zones for a league.

### Method
GET

### Endpoint
/standings/:leagueId/zones

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### GET /results/today

Source: https://goal-api.com/documentation

Get results for today's matches.

```APIDOC
## GET /results/today

### Description
Get today's results.

### Method
GET

### Endpoint
/results/today

```

--------------------------------

### GET /players/compare?ids=

Source: https://goal-api.com/documentation

Compare statistics of two players.

```APIDOC
## GET /players/compare?ids=

### Description
Compare two players.

### Method
GET

### Endpoint
/players/compare?ids=

### Parameters
#### Query Parameters
- **ids** (string) - Required - IDs of the two players to compare.

```

--------------------------------

### match_update message example

Source: https://goal-api.com/documentation

Example of a match_update message pushed when a subscribed match's state changes. The data includes match_id, match_status, clock details, scores, and arrays for goalscorer and cards.

```json
{
  "type": "match_update",
  "data": {
    "match_id": "781091",
    "match_status": "45+2",
    "clock": {
      "minute": "45+2",
      "elapsed": 45,
      "extra": 2,
      "period": "FIRST_HALF",
      "updatedAt": "2026-09-11T18:17:40.512Z"
    },
    "match_hometeam_score": "2",
    "match_awayteam_score": "1",
    "match_live": "1",
    "goalscorer": [ ... ],
    "cards": [ ... ]
  },
  "timestamp": 1783040229469
}
```

--------------------------------

### GET /videos

Source: https://goal-api.com/documentation

Retrieves a list of all video highlights available for matches and leagues.

```APIDOC
## GET /videos

### Description
Get all video highlights.

### Method
GET

### Endpoint
/videos

### Response
#### Success Response (200)
- Returns a list of video highlights.

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /players/:id

Source: https://goal-api.com/documentation

Get detailed profile of a specific player.

```APIDOC
## GET /players/:id

### Description
Get player profile.

### Method
GET

### Endpoint
/players/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the player.

```

--------------------------------

### GET /coaches/:id

Source: https://goal-api.com/documentation

Get detailed profile of a specific coach.

```APIDOC
## GET /coaches/:id

### Description
Get coach profile.

### Method
GET

### Endpoint
/coaches/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the coach.

```

--------------------------------

### GET /coaches/search?q=

Source: https://goal-api.com/documentation

Search for coaches by name using a query parameter.

```APIDOC
## GET /coaches/search?q=

### Description
Search coaches by name.

### Method
GET

### Endpoint
/coaches/search?q=

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query for coach name.

```

--------------------------------

### GET /players/:id/statistics

Source: https://goal-api.com/documentation

Get statistics for a specific player.

```APIDOC
## GET /players/:id/statistics

### Description
Get player statistics.

### Method
GET

### Endpoint
/players/:id/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the player.

```

--------------------------------

### GET /standings/:leagueId/home

Source: https://goal-api.com/documentation

Get the home standings (table of home matches) for a league.

```APIDOC
## GET /standings/:leagueId/home

### Description
Get home standings for a league.

### Method
GET

### Endpoint
/standings/:leagueId/home

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### GET /results/yesterday

Source: https://goal-api.com/documentation

Get results for yesterday's matches.

```APIDOC
## GET /results/yesterday

### Description
Get yesterday's results.

### Method
GET

### Endpoint
/results/yesterday

```

--------------------------------

### GET /coaches/country/:country

Source: https://goal-api.com/documentation

Get coaches from a specific country.

```APIDOC
## GET /coaches/country/:country

### Description
Get coaches by nationality.

### Method
GET

### Endpoint
/coaches/country/:country

### Parameters
#### Path Parameters
- **country** (string) - Required - The nationality of the coaches.

```

--------------------------------

### GET /results/stats

Source: https://goal-api.com/documentation

Get statistics related to match results.

```APIDOC
## GET /results/stats

### Description
Get results statistics.

### Method
GET

### Endpoint
/results/stats

```

--------------------------------

### error message example

Source: https://goal-api.com/documentation

Example of an error message sent when something goes wrong, such as authentication failure. The error object includes a code, message, and category to branch behavior.

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

--------------------------------

### GET /players/search?q=

Source: https://goal-api.com/documentation

Search for players by name using a query parameter.

```APIDOC
## GET /players/search?q=

### Description
Search players by name.

### Method
GET

### Endpoint
/players/search?q=

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query for player name.

```

--------------------------------

### GET /results/high-scoring

Source: https://goal-api.com/documentation

Get matches with high scoring games.

```APIDOC
## GET /results/high-scoring

### Description
Get high-scoring matches.

### Method
GET

### Endpoint
/results/high-scoring

```

--------------------------------

### GET /coaches

Source: https://goal-api.com/documentation

Retrieve a list of all coaches.

```APIDOC
## GET /coaches

### Description
Get all coaches.

### Method
GET

### Endpoint
/coaches

```

--------------------------------

### GET /results/date/:date

Source: https://goal-api.com/documentation

Get match results for a specific date.

```APIDOC
## GET /results/date/:date

### Description
Get results by date.

### Method
GET

### Endpoint
/results/date/:date

### Parameters
#### Path Parameters
- **date** (string) - Required - The date for which to retrieve results.

```

--------------------------------

### GET /standings/:leagueId

Source: https://goal-api.com/documentation

Get the league table for a specified league.

```APIDOC
## GET /standings/:leagueId

### Description
Get league table for a specific league.

### Method
GET

### Endpoint
/standings/:leagueId

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### GET /videos/date/:date

Source: https://goal-api.com/documentation

Retrieves video highlights for a specific date.

```APIDOC
## GET /videos/date/:date

### Description
Get videos by date.

### Method
GET

### Endpoint
/videos/date/:date

### Parameters
#### Path Parameters
- **date** (string) - Required - The date for which to retrieve videos.

### Response
#### Success Response (200)
- Returns a list of video highlights for the specified date.

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /players

Source: https://goal-api.com/documentation

Retrieve a list of all players.

```APIDOC
## GET /players

### Description
Get all players.

### Method
GET

### Endpoint
/players

```

--------------------------------

### GET /videos/recent

Source: https://goal-api.com/documentation

Retrieves the most recent video highlights.

```APIDOC
## GET /videos/recent

### Description
Get recent videos.

### Method
GET

### Endpoint
/videos/recent

### Response
#### Success Response (200)
- Returns a list of recent video highlights.

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /coaches/team/:teamId

Source: https://goal-api.com/documentation

Get the coach of a specific team.

```APIDOC
## GET /coaches/team/:teamId

### Description
Get team's coach.

### Method
GET

### Endpoint
/coaches/team/:teamId

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team.

```

--------------------------------

### GET /players/top/:stat

Source: https://goal-api.com/documentation

Get top players sorted by a given statistic.

```APIDOC
## GET /players/top/:stat

### Description
Get top players by statistic.

### Method
GET

### Endpoint
/players/top/:stat

### Parameters
#### Path Parameters
- **stat** (string) - Required - The statistic to rank players by.

```

--------------------------------

### GET /standings/:leagueId/form

Source: https://goal-api.com/documentation

Get the league standings including form indicators for each team.

```APIDOC
## GET /standings/:leagueId/form

### Description
Get standings with form information.

### Method
GET

### Endpoint
/standings/:leagueId/form

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### Subscribe to a match via WebSocket

Source: https://goal-api.com/documentation

After receiving auth_success, subscribe to a fixture by its match ID to start receiving live updates.

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

--------------------------------

### GET /results/league/:leagueId

Source: https://goal-api.com/documentation

Get match results for a specific league.

```APIDOC
## GET /results/league/:leagueId

### Description
Get results by league.

### Method
GET

### Endpoint
/results/league/:leagueId

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### GET /h2h/:team1Id/:team2Id

Source: https://goal-api.com/documentation

Get a summary of matches between two teams.

```APIDOC
## GET /h2h/:team1Id/:team2Id

### Description
Get head-to-head summary between two teams.

### Method
GET

### Endpoint
/h2h/:team1Id/:team2Id

### Parameters
#### Path Parameters
- **team1Id** (string) - Required - The ID of the first team.
- **team2Id** (string) - Required - The ID of the second team.

```

--------------------------------

### GET /standings/:leagueId/away

Source: https://goal-api.com/documentation

Get the away standings (table of away matches) for a league.

```APIDOC
## GET /standings/:leagueId/away

### Description
Get away standings for a league.

### Method
GET

### Endpoint
/standings/:leagueId/away

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.

```

--------------------------------

### GET /h2h/:team1Id/:team2Id/direct

Source: https://goal-api.com/documentation

Get the history of direct matches between two teams.

```APIDOC
## GET /h2h/:team1Id/:team2Id/direct

### Description
Get direct matches history.

### Method
GET

### Endpoint
/h2h/:team1Id/:team2Id/direct

### Parameters
#### Path Parameters
- **team1Id** (string) - Required - The ID of the first team.
- **team2Id** (string) - Required - The ID of the second team.

```

--------------------------------

### GET /results

Source: https://goal-api.com/documentation

Retrieve all completed match results.

```APIDOC
## GET /results

### Description
Get all completed matches.

### Method
GET

### Endpoint
/results

```

--------------------------------

### GET /results/team/:teamId

Source: https://goal-api.com/documentation

Get match results for a specific team.

```APIDOC
## GET /results/team/:teamId

### Description
Get results by team.

### Method
GET

### Endpoint
/results/team/:teamId

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team.

```

--------------------------------

### GET /news

Source: https://goal-api.com/documentation

Retrieves football news articles, sorted by publication date descending.

```APIDOC
## GET /news

### Description
Get news articles, newest first.

### Method
GET

### Endpoint
/news

### Response
#### Success Response (200)
- Returns a list of news articles, ordered by publication date (newest first).

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /h2h/:team1Id/:team2Id/stats

Source: https://goal-api.com/documentation

Get head-to-head statistics between two teams.

```APIDOC
## GET /h2h/:team1Id/:team2Id/stats

### Description
Get H2H statistics.

### Method
GET

### Endpoint
/h2h/:team1Id/:team2Id/stats

### Parameters
#### Path Parameters
- **team1Id** (string) - Required - The ID of the first team.
- **team2Id** (string) - Required - The ID of the second team.

```

--------------------------------

### GET /standings/:leagueId/team/:teamId

Source: https://goal-api.com/documentation

Get the position of a specific team in the league table.

```APIDOC
## GET /standings/:leagueId/team/:teamId

### Description
Get team position in the league table.

### Method
GET

### Endpoint
/standings/:leagueId/team/:teamId

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The ID of the league.
- **teamId** (string) - Required - The ID of the team.

```

--------------------------------

### Fixtures

Source: https://goal-api.com/documentation

Endpoints to get match schedules, live scores, lineups, events, statistics, and detailed match information. Kickoff times are UTC and use the kickoffUtc field.

```APIDOC
## GET /fixtures

### Description
Get all fixtures.

### Method
GET

### Endpoint
/fixtures

```

```APIDOC
## GET /fixtures/live

### Description
Get live matches.

### Method
GET

### Endpoint
/fixtures/live

```

```APIDOC
## GET /fixtures/date/:date

### Description
Get fixtures by date.

### Method
GET

### Endpoint
/fixtures/date/:date

### Parameters
#### Path Parameters
- **date** (string) - Required - Date in YYYY-MM-DD format.

```

```APIDOC
## GET /fixtures/:id

### Description
Get fixture details.

### Method
GET

### Endpoint
/fixtures/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/events

### Description
Get match events (goals, cards).

### Method
GET

### Endpoint
/fixtures/:id/events

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/lineups

### Description
Get match lineups.

### Method
GET

### Endpoint
/fixtures/:id/lineups

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/statistics

### Description
Get match statistics.

### Method
GET

### Endpoint
/fixtures/:id/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/cards

### Description
Get match cards.

### Method
GET

### Endpoint
/fixtures/:id/cards

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/substitutions

### Description
Get match substitutions.

### Method
GET

### Endpoint
/fixtures/:id/substitutions

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

```APIDOC
## GET /fixtures/:id/commentary

### Description
Minute-by-minute live commentary.

### Method
GET

### Endpoint
/fixtures/:id/commentary

### Parameters
#### Path Parameters
- **id** (string) - Required - Fixture ID.

```

--------------------------------

### GET /videos/league/:leagueId

Source: https://goal-api.com/documentation

Retrieves video highlights for a specific league identified by its league ID.

```APIDOC
## GET /videos/league/:leagueId

### Description
Get videos by league.

### Method
GET

### Endpoint
/videos/league/:leagueId

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The identifier of the league.

### Response
#### Success Response (200)
- Returns a list of video highlights for the specified league.

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /videos/match/:matchId

Source: https://goal-api.com/documentation

Retrieves video highlights for a specific match identified by its match ID.

```APIDOC
## GET /videos/match/:matchId

### Description
Get videos for a specific match.

### Method
GET

### Endpoint
/videos/match/:matchId

### Parameters
#### Path Parameters
- **matchId** (string) - Required - The identifier of the match.

### Response
#### Success Response (200)
- Returns a list of video highlights for the specified match.

#### Response Example
{
  "data": []
}

```

--------------------------------

### Leagues

Source: https://goal-api.com/documentation

Endpoints to get league information, standings, fixtures, teams, and top scorers for any football league.

```APIDOC
## GET /leagues

### Description
Get all leagues.

### Method
GET

### Endpoint
/leagues

```

```APIDOC
## GET /leagues/:id

### Description
Get league by ID.

### Method
GET

### Endpoint
/leagues/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

```APIDOC
## GET /leagues/:id/teams

### Description
Get teams in a league.

### Method
GET

### Endpoint
/leagues/:id/teams

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

```APIDOC
## GET /leagues/:id/standings

### Description
Get league standings.

### Method
GET

### Endpoint
/leagues/:id/standings

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

```APIDOC
## GET /leagues/:id/fixtures

### Description
Get league fixtures.

### Method
GET

### Endpoint
/leagues/:id/fixtures

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

```APIDOC
## GET /leagues/:id/top-scorers

### Description
Get league top scorers.

### Method
GET

### Endpoint
/leagues/:id/top-scorers

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

```APIDOC
## GET /leagues/:id/results

### Description
Get league results.

### Method
GET

### Endpoint
/leagues/:id/results

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID.

```

--------------------------------

### GET /news/:id

Source: https://goal-api.com/documentation

Retrieves a single news article by its unique identifier.

```APIDOC
## GET /news/:id

### Description
Get one article.

### Method
GET

### Endpoint
/news/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier of the news article.

### Response
#### Success Response (200)
- Returns a single news article.

#### Response Example
{
  "data": {}
}

```

--------------------------------

### GET /news/league/:leagueId

Source: https://goal-api.com/documentation

Retrieves news articles associated with a specific competition or league.

```APIDOC
## GET /news/league/:leagueId

### Description
Get news for a competition.

### Method
GET

### Endpoint
/news/league/:leagueId

### Parameters
#### Path Parameters
- **leagueId** (string) - Required - The identifier of the league/competition.

### Response
#### Success Response (200)
- Returns news articles related to the specified league.

#### Response Example
{
  "data": []
}

```

--------------------------------

### Get WebSocket connection token

Source: https://goal-api.com/documentation

Exchange your API key for a short-lived, single-use connection token (valid for 60 seconds) via a POST request to /v1/ws/token. The token is consumed the moment it's used.

```javascript
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)
```

--------------------------------

### GET /news/match/:matchId

Source: https://goal-api.com/documentation

Retrieves news articles associated with a specific match.

```APIDOC
## GET /news/match/:matchId

### Description
Get news for a match.

### Method
GET

### Endpoint
/news/match/:matchId

### Parameters
#### Path Parameters
- **matchId** (string) - Required - The identifier of the match.

### Response
#### Success Response (200)
- Returns news articles related to the specified match.

#### Response Example
{
  "data": []
}

```

--------------------------------

### GET /news/team/:teamId

Source: https://goal-api.com/documentation

Retrieves news articles associated with a specific team.

```APIDOC
## GET /news/team/:teamId

### Description
Get news for a team.

### Method
GET

### Endpoint
/news/team/:teamId

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The identifier of the team.

### Response
#### Success Response (200)
- Returns news articles related to the specified team.

#### Response Example
{
  "data": []
}

```

--------------------------------

### Filter webhook endpoint by league IDs with curl PATCH

Source: https://goal-api.com/documentation

Use this curl command to update a webhook endpoint's leagueIds filter. The IDs come from GET /leagues (either id or apiId) or GET /auth/webhook-endpoints/leagues. An empty array turns the filter off, reverting to the default of receiving events from every competition. Note: this endpoint uses the session token, not the API key.

```bash
# 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.goal-api.com/v1/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": [] }'
```

--------------------------------

### Connect and authenticate WebSocket

Source: https://goal-api.com/documentation

Open the WebSocket with the token as a query parameter, then send it again as the first message to complete authentication.

```javascript
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);
};
```

--------------------------------

### WebSocket wss://api.goal-api.com/ws

Source: https://goal-api.com/documentation

Establishes a persistent WebSocket connection for live match data, requiring token-based authentication and subscription by match ID.

```APIDOC
## WebSocket wss://api.goal-api.com/ws

### Description
Subscribe to a match and receive live score, event, and statistics updates over a persistent WebSocket connection.

### Connection
Endpoint: wss://api.goal-api.com/ws

### Authentication
Use a connection token (obtained via POST /v1/ws/token) as a query parameter and as the first message to complete authentication. Alternatively, server-side clients may set an Authorization header on the handshake and send `{"type":"auth","apiKey":"YOUR_API_KEY"}`.

### Subscribe to a match
Send a message with type `subscribe`, resource `match`, and the `matchId` to receive updates.

### Message Examples
#### Auth
{"type":"auth","token":"..."}

#### Subscribe
{"type":"subscribe","resource":"match","matchId":"12345"}

### Response
- **auth_success** - Indicates authentication succeeded.
- Live updates include types such as score, events, and statistics.

```

--------------------------------

### Expose local endpoint with ngrok

Source: https://goal-api.com/documentation

Use ngrok to expose your local webhook endpoint to the public internet. The output URL (e.g., https://abc123.ngrok-free.app) should be registered as your webhook URL.

```bash
ngrok http 3000
```

--------------------------------

### Sample JSON Response with Success Flag and Pagination

Source: https://goal-api.com/documentation

Every response is JSON with a success flag and a data payload; list endpoints add pagination. The pagination object includes total, limit, offset, and hasMore fields.

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

--------------------------------

### API Resources

Source: https://goal-api.com/documentation

Lists the API resources available in the GOAL API, including webhooks, countries, leagues, teams, fixtures, standings, players, coaches, head-to-head, results, videos, and news, with endpoint counts for each resource.

```APIDOC
## [GET] /leagues

### Description
Fetches a list of football leagues. This endpoint is used to demonstrate authentication with a Bearer token.

### Method
GET

### Endpoint
https://api.goal-api.com/v1/leagues

### Headers
- **Authorization** (string) - Required - Bearer token for authentication

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

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request succeeded
- **data** (object) - The payload containing the requested data
- **pagination** (object) - Present if the endpoint returns a list

#### Response Example
```json
{
  "success": true,
  "data": {},
  "pagination": {
    "total": 100,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```
```

--------------------------------

### MCP Server Configuration for Goal API

Source: https://goal-api.com/documentation

Add this JSON configuration to your MCP client to connect to the hosted Goal API MCP server. Use your existing API key in the Authorization header. Every tool call counts as one request against your plan.

```json
{
  "mcpServers": {
    "goal-api": {
      "url": "https://mcp.goal-api.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

--------------------------------

### Authenticate with Bearer Token using curl

Source: https://goal-api.com/documentation

Send a request to the leagues endpoint with your API key as a Bearer token. Requests without a valid key return a 401 error. Keep your key secret and treat it like a password.

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

--------------------------------

### Verify webhook signature in Node.js/Express

Source: https://goal-api.com/documentation

This Express route verifies the X-Goal-Signature header on incoming webhook POSTs. It uses the raw request body (express.raw) because re-serialized JSON will not match the signature. It performs a constant-time comparison with crypto.timingSafeEqual and rejects requests older than five minutes to prevent replay attacks. Respond with 2xx quickly; non-2xx responses are retried with backoff (1m, 5m, 25m, 2h, 10h) and the request times out after 8 seconds.

```javascript
// 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);
  }
);
```

--------------------------------

### POST /v1/ws/token

Source: https://goal-api.com/documentation

Obtains a short-lived, single-use connection token for WebSocket authentication by sending your API key as a bearer token.

```APIDOC
## POST /v1/ws/token

### Description
Exchange your API key for a short-lived, single-use connection token (valid for 60 seconds). This is a normal authenticated HTTP request.

### Method
POST

### Endpoint
/v1/ws/token

### Request
#### Headers
- **Authorization** (string) - Required - Bearer token containing your API key.

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

### Response
#### Success Response (200)
- **data.token** (string) - The connection token.
- **data.expiresIn** (number) - Validity period in seconds.

#### Response Example
{
  "data": {
    "token": "...",
    "expiresIn": 60
  }
}

```

--------------------------------

### Teams

Source: https://goal-api.com/documentation

Endpoints to access team data, squad information, fixtures, results, and detailed statistics.

```APIDOC
## GET /teams

### Description
Get all teams.

### Method
GET

### Endpoint
/teams

```

```APIDOC
## GET /teams/:id

### Description
Get team by ID.

### Method
GET

### Endpoint
/teams/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

```APIDOC
## GET /teams/:id/players

### Description
Get team squad.

### Method
GET

### Endpoint
/teams/:id/players

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

```APIDOC
## GET /teams/:id/fixtures

### Description
Get team fixtures.

### Method
GET

### Endpoint
/teams/:id/fixtures

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

```APIDOC
## GET /teams/:id/results

### Description
Get team results.

### Method
GET

### Endpoint
/teams/:id/results

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

```APIDOC
## GET /teams/:id/statistics

### Description
Get team statistics.

### Method
GET

### Endpoint
/teams/:id/statistics

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

```APIDOC
## GET /teams/:id/upcoming

### Description
Get upcoming fixtures.

### Method
GET

### Endpoint
/teams/:id/upcoming

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID.

```

--------------------------------

### Expose local endpoint with cloudflared

Source: https://goal-api.com/documentation

Use cloudflared to create a tunnel to your local webhook endpoint. This provides a public URL for testing webhooks.

```bash
cloudflared tunnel --url http://localhost:3000
```

--------------------------------

### Countries

Source: https://goal-api.com/documentation

Endpoints to access country data and retrieve leagues associated with specific countries.

```APIDOC
## GET /countries

### Description
Get all countries.

### Method
GET

### Endpoint
/countries

```

```APIDOC
## GET /countries/:id

### Description
Get country by ID.

### Method
GET

### Endpoint
/countries/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - Country ID.

```

```APIDOC
## GET /countries/:id/leagues

### Description
Get leagues for a country.

### Method
GET

### Endpoint
/countries/:id/leagues

### Parameters
#### Path Parameters
- **id** (string) - Required - Country ID.

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.