Sofascore adapter

Sofascore: Live status and result cards.

Sofascore is the richest free source for live match state. The adapter decodes their status codes and type buckets (scheduled, live, halftime, finished, postponed, cancelled, abandoned) and gives you back a consistent MatchSummary that works for both live scoreboards and historical result cards.

All adapters What you can build

Input shape

A Sofascore match event object (from their API or a scrape).

Status

Narrow (scrape-backed)

Raw feed

Sofascore

Provider-shaped. Their coordinates, their qualifier codes, their outcome strings.

Messy

Campos adapter

fromSofascore.matchSummary(event)

Flips direction, standardises outcomes, filters own-goals and shootouts, resolves player labels.

One call

Typed data

MatchSummary

Drop into <ShotMap />, your own React view, a server-side report, or an analysis script.

Ready

Best for live scoreboards

Sofascore is the only adapter here that natively understands live states — the halftime code, in-play vs full time, the penalty-shootout resolution — without needing a second provider. If you're building a live match strip, start here.

Get it running

One import, one call per surface.

import { fromSofascore } from "@withqwerty/campos-adapters";

const summary = fromSofascore.matchSummary(matchEvent);

What this adapter ships

The calls you can make today.

Shipped

matchSummary() returns MatchSummary

Scoreline, status, and team-level xG.

Sofascore notes: Full status-code decoding, including live states and shootout penalties.

What you can build with this

Charts that drop straight onto this adapter's output.

Supported cards plot from this adapter with no extra work. Partial cards plot, but read the scope note. Dimmed cards need a surface this provider doesn't ship.

Pitch charts

Plot events, shots, passes, and formations directly on the pitch.

ShotMap

Needs shots() — not shipped on Sofascore yet.

PassMap

Needs passes() — not shipped on Sofascore yet.

PassFlow

Needs passes() — not shipped on Sofascore yet.

PassNetwork

Needs passes() — not shipped on Sofascore yet.

PassSonar

Needs passes() — not shipped on Sofascore yet.

Heatmap

Needs events() — not shipped on Sofascore yet.

KDE

Needs events() — not shipped on Sofascore yet.

Territory

Needs events() — not shipped on Sofascore yet.

Formation

Needs formations() — not shipped on Sofascore yet.

Match-time + xG

Time-series and xG-driven views from shots().

XGTimeline

Needs per-shot xG — Sofascore doesn't provide it.

Bring your own aggregates

These charts are adapter-independent — they take pre-aggregated inputs.

ScatterPlot

Takes pre-aggregated data. No adapter dependency.

RadarChart

Takes pre-aggregated data. No adapter dependency.

PizzaChart

Takes pre-aggregated data. No adapter dependency.

BumpChart

Takes pre-aggregated data. No adapter dependency.

LineChart

Takes pre-aggregated data. No adapter dependency.

CometChart

Takes pre-aggregated data. No adapter dependency.

Beeswarm

Takes pre-aggregated data. No adapter dependency.

DistributionChart

Takes pre-aggregated data. No adapter dependency.

PercentileSurfaces

Takes pre-aggregated data. No adapter dependency.

StatBadge

Takes pre-aggregated data. No adapter dependency.

Status codes, decoded

Sofascore's state model is richer than most.

Sofascore's status object has both a code (numeric) and a type (coarse bucket). The adapter prefers type and uses code to refine edge cases like halftime, extra time, and shootout resolutions. The full decoding table:

{
  "scheduled": [
    0,
    "type: notstarted"
  ],
  "live": [
    6,
    7,
    8,
    9,
    "type: inprogress"
  ],
  "halftime": [
    31,
    41,
    50
  ],
  "finished": [
    100,
    110,
    120,
    130,
    140,
    "type: finished"
  ],
  "postponed": [
    60,
    "type: postponed"
  ],
  "cancelled": [
    70,
    "type: canceled"
  ],
  "abandoned": [
    90
  ]
}

Current scope

What's honest about this adapter today.

What it's great for

Live states and result cards.

Halftime markers, in-play scoreboards, shootout resolutions, historical result cards — matchSummary() handles all of them from the same Sofascore payload.

What it doesn't do

No events, shots, passes, or lineups.

Sofascore publishes richer detail behind per-match endpoints, but the current Campos adapter stays summary-only. Expand as the community needs justify it.

Where the event object comes from

Scrape or API; adapter takes the object.

The adapter accepts the Sofascore match event object directly — whether you hit their API, use ScraperFC, or maintain your own scraper. Field names match Sofascore's native shape.

Lineage

What this adapter borrows from whom.

Concrete credits for the projects that did the underlying research or laid the reference tables we read from.

ScraperFC Python

Sofascore status-code table and WhoScored match-centre structure references.

Raw example — what the payload looks like before and after

Raw Sofascore match event

{
  "id": 12529128,
  "status": {
    "code": 100,
    "description": "Ended",
    "type": "finished"
  },
  "startTimestamp": 1724011200,
  "homeTeam": {
    "id": 17,
    "name": "Manchester City"
  },
  "awayTeam": {
    "id": 38,
    "name": "Chelsea"
  },
  "homeScore": {
    "current": 2,
    "penalties": null
  },
  "awayScore": {
    "current": 0,
    "penalties": null
  },
  "tournament": {
    "name": "Premier League"
  },
  "season": {
    "name": "24/25",
    "year": 2024
  },
  "venue": {
    "name": "Etihad Stadium"
  },
  "roundInfo": {
    "round": 1
  }
}

Canonical MatchSummary

{
  "matchId": "12529128",
  "competitionLabel": "Premier League",
  "seasonLabel": "24/25",
  "kickoff": "2024-08-18T20:00:00.000Z",
  "status": "finished",
  "statusLabel": "Ended",
  "venue": "Etihad Stadium",
  "home": {
    "teamId": "17",
    "teamLabel": "Manchester City",
    "score": 2
  },
  "away": {
    "teamId": "38",
    "teamLabel": "Chelsea",
    "score": 0
  },
  "sourceMeta": {
    "statusCode": 100,
    "statusType": "finished",
    "round": 1
  }
}

Compare providers