Quickstart

This guide walks you from zero to a working API call in five minutes.

Sports

Every endpoint exists under both /v1/football/... and /v1/basketball/.... The two paths are sister copies — same shape, same parameters, different sport. Examples on this page use football, but swap the prefix and they work identically for basketball.

1. Get an API key

Sign in to the Scorelytics dashboard, open Settings → API keys, and click Create key. Copy the key — it will not be shown again.

Key prefixes

Keys are prefixed sk_live_ for production and sk_test_ for staging. Mixing them is the most common cause of 401s in the wild.

2. Send your first request

The "list matches" endpoint is the canonical hello-world.

curl

curl https://api.scorelytics.pro/v1/football/matches \
  -H "X-API-Key: sk_live_..."

Node.js (fetch)

const res = await fetch(
  'https://api.scorelytics.pro/v1/football/matches',
  { headers: { 'X-API-Key': process.env.SCORELYTICS_KEY } }
);
const { data } = await res.json();
console.log(data);

Python (requests)

import os, requests

r = requests.get(
    "https://api.scorelytics.pro/v1/football/matches",
    headers={"X-API-Key": os.environ["SCORELYTICS_KEY"]},
)
r.raise_for_status()
print(r.json()["data"])

Go (net/http)

req, _ := http.NewRequest("GET",
    "https://api.scorelytics.pro/v1/football/matches", nil)
req.Header.Set("X-API-Key", os.Getenv("SCORELYTICS_KEY"))
res, err := http.DefaultClient.Do(req)
// handle err, decode JSON…

You should get a JSON body that looks like:

{
  "data": [
    {
      "id": "abc123",
      "league_id": "DEf456",
      "home_team": "Real Madrid",
      "away_team": "Barcelona",
      "home_score": 2,
      "away_score": 1,
      "status_code": 2,
      "minute": 67,
      "kickoff_ts": 1746369000,
      "updated_at": "2026-05-04T16:32:11Z"
    }
  ],
  "total": 1,
  "limit": 50
}

3. Filter the response

Add query parameters to narrow the result:

# Only live matches
curl "https://api.scorelytics.pro/v1/football/matches?status=live" \
  -H "X-API-Key: sk_live_..."

# A specific league, ordered by kickoff
curl "https://api.scorelytics.pro/v1/football/matches?league_id=DEf456" \
  -H "X-API-Key: sk_live_..."

# A specific date in UTC
curl "https://api.scorelytics.pro/v1/football/matches?date=2026-05-04" \
  -H "X-API-Key: sk_live_..."

See the full filter list on the listMatches reference.

4. Drill into a single match

Pick a match ID from the previous response and ask for the full record:

curl https://api.scorelytics.pro/v1/football/matches/abc123 \
  -H "X-API-Key: sk_live_..."

You now have referee, venue, attendance, formations, half-time scores and the period/minute. From here, common follow-ups are:

• GET /v1/football/matches/{id}/events — chronological timeline.
• GET /v1/football/matches/{id}/stats — possession, shots, etc.
• GET /v1/football/matches/{id}/lineups — starting XI + bench.

5. (Optional) Subscribe to live updates

For a continuously updating UI, switch from polling to WebSocket:

const ws = new WebSocket(
  'wss://api.scorelytics.pro/v1/ws/match/abc123?api_key=sk_live_...'
);
ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  if (update.type === 'score_update') {
    document.getElementById('score').textContent =
      `${update.data.home}-${update.data.away}`;
  }
};

See the WebSocket guide for the full message format.

What's next?

• Authentication — API key best practices.
• Live scoreboard guide — full walk-through.
• API Reference — every endpoint, with schemas and examples.