DEV Community: Miheve

How to Build a Sports Data FastAPI Gateway with Sportmicro

Miheve — Sun, 20 Sep 2026 13:19:33 +0000

When I started this project, I wanted a small but realistic way to show how a backend can sit in front of a sports data provider without turning into a thin, leaky proxy. The goal was to build a sports data FastAPI gateway that feels production-style: environment-based configuration, a typed client, explicit resource mapping, and predictable responses for consumers who want to work with Sportmicro data through a clean interface.

The repository is an open-source example of that shape, powered by Sportmicro. It does not try to model the entire upstream API. Instead, it focuses on a practical subset and shows the integration boundary clearly. If you want to inspect the code while reading, View the repository.

Why a gateway instead of a direct proxy

The first thing I wanted to avoid was spreading upstream details throughout the app. When a product talks directly to a sports data API, three things tend to happen quickly:

credentials appear in too many places,
response shapes leak into every layer,
error handling becomes inconsistent.

A gateway solves that by putting the upstream integration behind one service boundary.

In this project, FastAPI is the public interface, but Sportmicro remains the provider behind the scenes. That matters because the application owns the contract it exposes to consumers. The gateway returns a stable, developer-facing payload with a source, endpoint, count, preview items, applied filters, and an optional note when no results are found.

The other practical reason for this shape is that sports data is naturally filter-heavy. A consumer might search by league, season, team, player, match, date, or status type. A gateway gives us one place to define which filters are allowed and how they are translated to the upstream API.

The architecture I used

The repository is intentionally small, but the separation of responsibilities is clear.

app/config.py reads settings from the environment.
app/sportmicro_client.py handles outbound HTTP calls to Sportmicro.
app/services.py maps supported resources to known Sportmicro endpoints.
app/main.py defines the FastAPI app and route behavior.
app/models.py defines the query and response structures.

That split is the core of the implementation.

Configuration stays at the edge

Settings reads SPORTMICRO_API_KEY plus optional base URLs and timeout settings from environment variables. The defaults in the code are already aligned to Sportmicro’s football, basketball, and tennis hosts, and get_settings() is cached with lru_cache(maxsize=1). That means configuration is loaded once and reused.

This is a simple choice, but it keeps secrets out of route handlers and makes the app easier to configure locally. It also gives the gateway a single place to adjust upstream hosts if needed.

The client does one job

The SportmicroClient class is deliberately narrow. It checks that an API key exists, expects an injected HTTP client in this environment, builds a query string, attaches the Bearer token, and raises a SportmicroClientError when something goes wrong.

A small excerpt shows the shape:

headers = {"Authorization": f"Bearer {self._api_key}"}
response = await self._client.get(url, headers=headers)
response.raise_for_status()

That is the right level of responsibility for this layer. It does not try to interpret business rules. It just translates a request into an upstream call and turns low-level failures into a controlled error path.

The service layer owns resource mapping

The service layer is where the gateway becomes opinionated. RESOURCE_MAP explicitly lists supported resource keys such as football-teams, football-players, football-matches, basketball-matches, and tennis-rankings. Each key maps to a SportmicroEndpoint with a source, base URL, and path.

That explicit list is important. Rather than building a generic “forward any path” proxy, the app only exposes resources that are intentionally supported. That keeps the contract understandable and reduces the chance of accidentally promising something the upstream provider does not document.

The service also translates the query object into upstream parameters. It uses order for the sort value, which is a good example of where the gateway is allowed to adapt the API without exposing the upstream shape directly to every caller.

How the request flow works

The main request path is straightforward, and that is part of the point.

The app uses a FastAPI lifespan function to create the client once at startup, store the settings and service on app.state, and close the client on shutdown. From there, route handlers can focus on request and response behavior instead of lifecycle management.

The /resources/{resource} route accepts a set of query parameters:

league_id
season_id
team_id
player_id
match_id
name
date
status_type
limit
offset
lang
sort

These are assembled into a SportmicroQuery, then handed to SportmicroService.list_resource().

From there, the flow is:

check whether the requested resource is supported,
resolve the matching upstream endpoint,
translate the query into upstream parameters,
fetch the list from Sportmicro,
build a response with source, endpoint, count, preview items, filters, and an optional note.

The route also handles errors at the edge. If the client raises SportmicroClientError, the app returns a 502-style JSON response with a detail message and retry_after_seconds: 60. That keeps the gateway honest: the failure is upstream, not local.

One detail I appreciated is the empty-state handling. If Sportmicro returns no items, the gateway does not treat that as an error. Instead, it adds a note suggesting the user widen the search or remove optional filters. For sports data, that is a sensible default because a narrow query is often valid even when it produces nothing.

Data modeling and response shaping

The repository uses dataclasses instead of a heavier schema stack. That keeps the code easy to follow while still providing structure.

SportmicroQuery is the input shape. It includes defaults for pagination and language, and it has a validate() classmethod that rejects unexpected fields. That method is a small guardrail against accidental input drift.

ResourcePreview is the output shape for the preview list. It intentionally selects a limited set of commonly useful fields:

id
name
description
status_type
start_time
league_id
season_id
team_id
player_id
match_id

The service converts raw items into preview objects and then back to dictionaries. That means the API response stays concise even if the upstream payload includes more detail.

I think this is a useful pattern for sports data APIs in general. A gateway does not have to expose every field from the provider. It can present the smallest stable subset that helps clients search, inspect, and decide what to fetch next.

Challenges and trade-offs

The main trade-off here was intentional scope, not a dramatic implementation problem.

The code supports a small, explicit set of resources instead of trying to mirror all Sportmicro endpoints. That choice keeps the gateway accurate and easy to reason about, but it also means the project is not a universal proxy. In practice, that is a feature: the app only exposes the football, basketball, and tennis resources already represented in the repository.

Another constraint is the backend-only design. There is no browser UI, so the repository leans on FastAPI’s OpenAPI docs and JSON responses rather than a frontend experience. That keeps the example focused on integration architecture rather than presentation.

A final design consideration is transport handling. The client expects an HTTP client to be available in the runtime environment, and the repository’s shape suggests the app is built around a controlled async backend context rather than a fully embedded HTTP stack. That keeps the example clean, but it also means the transport boundary matters when you extend or test the app.

Local setup and testing

The repository includes enough evidence to describe local setup safely.

The README shows the expected workflow:

pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

It also documents the required SPORTMICRO_API_KEY environment variable and optional base URLs for football, basketball, tennis, plus a timeout setting. Once the server is running, the API root, /health, and /docs are available locally.

For validation, the repository also documents two useful checks:

python3 -m compileall -q .
python3 -m unittest discover -s tests

That lines up with the presence of a test suite under tests/, which is a good sign that the project is meant to be exercised rather than just read.

Project shape at a glance

Here is the compact structure I kept in mind while building:

app/
  config.py
  main.py
  models.py
  services.py
  sportmicro_client.py
tests/
  test_app.py
  test_client.py
  test_main.py
  test_models.py

That tree is small enough to understand quickly, but it still reflects a real backend boundary: configuration, transport, service logic, and API surface are all separated.

What I would improve next

A few future improvements stand out if you wanted to evolve this gateway further:

add more documented Sportmicro resources to the explicit map,
expand response modeling for endpoints that have stable, known shapes,
add caching where upstream update frequency makes sense,
broaden tests around error paths and empty-state responses,
consider a richer response contract for consumers that need deeper data than the current preview list.

I would keep those as deliberate extensions, not assumptions. The current repository does one thing clearly: it demonstrates how to wrap Sportmicro data in a clean FastAPI gateway without overcomplicating the integration.

Takeaway

The main lesson from this build is that a useful sports data gateway does not have to be large to be valuable. If the configuration is centralized, the client is narrow, the resource mapping is explicit, and the response contract is stable, consumers get something they can actually build against.

That is the part I would reuse in another integration: keep the provider-specific details at the edge, expose only the resources you truly support, and make empty results and upstream failures behave predictably. For sports APIs, that discipline is often more useful than broad surface area.

How to Build a NCAA Football Schedule Tracker with Sportmicro

Miheve — Sun, 20 Sep 2026 12:04:48 +0000

I built this project because sports API demos often stop at “it renders data” and skip the part that actually matters in a real app: what happens when the payload is partial, empty, or unavailable. For an NCAA football schedule tracker, that’s the interesting problem. A schedule browser only feels trustworthy if it can show a clean table, explain loading, and fail gracefully when the provider doesn’t return what you expected.

The goal of this repository was to make a small, production-style React app that demonstrates how to use Sportmicro as a real sports data provider without pretending the project is a full sports platform. If you want to inspect the code alongside this write-up, you can View the repository.

What I set out to prove

The scope is intentionally narrow: browse NCAA football fixtures, filter them by date and keyword, and make the app honest about loading and failure states. That narrowness is the point. It forces the integration decisions to be visible instead of hiding them behind a large feature set.

The app is built around a few principles I wanted to demonstrate:

the API client lives separately from the UI
provider responses are normalized before rendering
environment-based configuration keeps secrets out of the repo
the UI handles loading, empty, and error states explicitly

That combination makes the project more useful than a toy fetch-and-print example. It’s a practical ncaa football schedule tracker API reference for anyone building with an American football API or a broader sports data API.

Architecture: keep the Sportmicro boundary explicit

The code is split into three layers:

src/lib/sportmicroClient.ts handles API access
src/lib/fixtures.ts reshapes raw data for display
src/ui/App.tsx owns page state and rendering

That boundary is the main architectural decision in the repo. It keeps the Sportmicro-specific details out of the React tree, which matters because API integration tends to get messy as soon as you mix request logic, parsing, and UI state in one component.

The client module centralizes authentication and fetch behavior. It uses the American football base URL, reads SPORTMICRO_API_KEY from the environment, and throws a clear error if the key is missing or if Sportmicro responds with a non-2xx status.

A compact excerpt shows the pattern:

async function requestJson<T>(path: string, searchParams: Record<string, string | undefined> = {}): Promise<T> {
  const url = new URL(path, API_BASE_URL);
  Object.entries(searchParams).forEach(([key, value]) => {
    if (value) url.searchParams.set(key, value);
  });

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${getApiKey()}`,
      Accept: 'application/json',
    },
  });

  if (!response.ok) {
    throw new SportmicroError(`Sportmicro request failed with ${response.status} ${response.statusText}`, response.status);
  }

  return (await response.json()) as T;
}

This helper does three useful things:

it keeps the base URL in one place
it injects the API key consistently
it turns provider errors into a message the UI can surface directly

That’s the sort of boundary that pays off later if the provider changes shape. The React code does not need to know how request headers are built or how query params are encoded.

How Sportmicro is integrated

This app uses three Sportmicro endpoints in the current implementation:

GET /leagues
GET /teams-by-league
GET /matches-by-date-league

The client exposes a function for each endpoint, which is a sensible fit for a small schedule browser. The UI loads the three data sets together when the selected date changes, then combines them into one view.

A few implementation choices are worth calling out:

getUpcomingMatches(date) sends league_id=eq.ncaaf and optionally filters by date
getTeamsByLeague(leagueId) requests team data for the chosen league
getLeagues() fetches a short league list for the summary cards

In App.tsx, those calls are coordinated with Promise.all:

const [leagueData, teamData, matchData] = await Promise.all([
  getLeagues(),
  getTeamsByLeague(DEFAULT_LEAGUE),
  getUpcomingMatches(selectedDate),
]);

I like this because the screen stays coherent. Instead of rendering one section immediately and letting the rest trickle in, the app waits until the core data is ready. That makes the page feel more deliberate and easier to reason about.

The authentication path is also intentionally simple: the repo includes .env.example, and the key lives in SPORTMICRO_API_KEY. That keeps secrets out of the repository and makes the setup flow obvious for anyone cloning the project.

Turning raw matches into UI-ready fixtures

The second layer is src/lib/fixtures.ts, which handles normalization and filtering. This file does the unglamorous work that makes the UI simple.

The flow is:

normalizeTeams() turns the team list into a lookup map
resolveFixtures() attaches homeTeam and awayTeam objects to each match
filterFixtures() narrows the list by date and search text

That separation matters because raw API data is rarely shaped for the exact screen you want. In this project, a match may arrive with missing team names or timestamps, so the UI needs sensible fallbacks. The normalized fixture model gives the component display-friendly values like displayDate, displayTime, and statusLabel.

The filter logic shows the kind of practical compromise I wanted:

const teamText = `${fixture.homeTeam?.name ?? ''} ${fixture.awayTeam?.name ?? ''}`.toLowerCase();

The search feature only needs to support team names and fixture IDs, so the helper keeps that logic outside the component tree. That means the React layer stays focused on state and rendering, while the data layer handles the awkward parts of partial provider responses.

What the UI does, and why it stays small

The interface is deliberately modest. It has:

a date picker
a search field
a fixtures table
three summary cards

That’s enough to demonstrate the Sportmicro integration without turning the project into a fake sports portal. The application state in src/ui/App.tsx stays readable:

selectedDate defaults to today
search filters by team name or fixture ID
isLoading and error control the screen state
leagues, teams, and fixtures store the fetched data

The most useful part of the UI is how explicitly it handles the three main states:

Loading: show a loading message while the requests are in flight
Error: surface the message from SportmicroError, including the missing-key case
Empty: explain that no fixtures may exist for the chosen date or filter

That empty state is important. Sports APIs often return valid but sparse data, and the app doesn’t invent records or pretend something is broken just because the date has no matches.

The table itself stays minimal. Each row shows the matchup, date, time, and status. If team data is missing, the UI falls back to the team ID or an “unavailable” label instead of crashing or hiding the row. That’s exactly the kind of defensive rendering I want in a live API demo.

Project tree and local setup

The source layout is compact:

src/
  lib/
    fixtures.ts
    sportmicroClient.ts
  ui/
    App.tsx
  main.tsx
  styles.css
  types.ts

The rest of the repository is standard Vite and TypeScript scaffolding, plus tests and build configuration.

Local setup is supported by the repository, so these steps are safe to follow:

Install dependencies with npm install
Copy .env.example to .env
Add your Sportmicro API key as SPORTMICRO_API_KEY
Run the app with npm run dev

The repository also supports build and test commands:

npm run build
npm test

That matters because it shows the project is not just a live demo with a UI shell. The source is set up to compile, build, and test the integration layer in a repeatable way.

Challenges and trade-offs

I didn’t approach this as a “solve everything” sports app. The design constraints were more practical:

keep the provider boundary explicit
avoid hardcoding secrets
handle partial or missing fields honestly
stay focused on schedule browsing instead of live scoring, standings, or player analytics

Those trade-offs show up in the code. The app uses a limited set of endpoints and a single league filter, and it prefers clear fallback text over inventing data. That keeps the implementation understandable and keeps the UI aligned with what the provider actually returns.

Another trade-off is that the app uses the current data shape from Sportmicro directly, with just enough normalization to make the interface stable. That’s a good fit for a small reference project, even if a larger production app would likely add deeper validation and caching around the API boundary.

What I’d improve next

A few future improvements stand out naturally from the current codebase:

stronger runtime validation of Sportmicro responses
more detailed fixture status presentation
additional NCAA-focused filters
pagination if the selected date returns a larger fixture list

Those are all reasonable next steps, but I’d keep the same architecture if I added them. The client should stay the only place that knows how to talk to Sportmicro, while the UI should remain focused on state and rendering.

If I extended the project further, I’d also consider making the filter experience a little richer without expanding the scope too far. The current version proves the data flow; the next step would be refining how a developer inspects and navigates that data.

Takeaway

The main lesson from this build is simple: a good sports API integration is less about fancy UI and more about treating the provider boundary seriously. In this project, the API client is isolated, the fetched data is normalized, and the UI is honest about loading and empty states.

That combination makes the app useful as both a schedule tracker and a reference implementation. If you’re building against Sportmicro, the pattern here should translate well: keep the request layer small, normalize the response once, and let the UI render only the data it can trust.

Building a Football Fixture MCP Server with Sportmicro API

Miheve — Sat, 19 Sep 2026 19:52:59 +0000

I built this project around a simple problem: football fixture data is easy to query in isolation, but hard to expose cleanly to AI clients without turning the integration into a mess of loosely validated endpoints. My goal with this repository was to create a read-only Model Context Protocol server that lets an MCP client ask grounded questions about football fixtures, match details, incidents, and lineups through the Sportmicro API, while keeping the surface area intentionally small.

That shape matters. Instead of trying to mirror the whole API, I focused on a narrow research layer: enough tools to answer fixture questions reliably, but not so many that the server becomes difficult to reason about or trust. The result is a TypeScript MCP server built with @modelcontextprotocol/sdk, zod, and a typed Sportmicro client.

View the repository

The architecture I used

The implementation is split into three parts:

server.ts defines the MCP tools and validates tool input
sportmicro-client.ts handles HTTP requests to Sportmicro
test/server.test.ts checks validation and error handling without needing a live API call

That separation keeps the MCP layer thin. The server is responsible for turning tool calls into structured responses, but it does not know how to build URLs or authenticate requests. The client owns those HTTP details. That line between “protocol” and “provider integration” is what keeps the code maintainable.

The data flow is straightforward:

An MCP client calls one of the registered tools.
The server validates the input with zod.
The Sportmicro client sends the request with the API key as a Bearer token.
The server returns structured text so the caller can distinguish success from failure.

A small detail I appreciate here is that the server is intentionally read-only. It does not mutate any Sportmicro data, and it only exposes the documented football endpoints needed for fixture research. That keeps the contract predictable for downstream clients.

Why a narrow MCP surface works here

I’ve found that MCP servers can grow too quickly if you expose every upstream endpoint just because it exists. This project takes the opposite approach: expose only the tools that match the actual research workflow.

In this repository, that means five tools:

search_matches_by_date
search_matches_by_date_and_league
get_match_by_id
get_match_incidents
get_match_lineups

That small tool set is enough to answer common football research questions without encouraging speculative behavior. It also makes the server easier to validate. For example, search_matches_by_date requires a date in YYYY-MM-DD format, while search_matches_by_date_and_league adds a league ID and optional pagination fields. Inputs are checked before any upstream request is made, which is exactly what I want in a server that sits between an AI client and a third-party API.

The Sportmicro integration itself is equally focused. The client points at the football API and maps each operation to a documented endpoint:

/matches-by-date
/matches-by-date-league
/matches
/matches-incidents
/matches-lineups

That decision matters because it avoids inventing fields or behavior that aren’t present in the provider documentation. When you’re building an AI-facing integration, being precise is more valuable than being broad.

How the implementation flows

The core implementation lives in src/server.ts. I like how compact it is, because the code reveals the actual contract without a lot of framework noise.

A useful pattern here is the structuredPayload and errorPayload pair. Both return JSON text wrapped in MCP content blocks, which keeps the output machine-readable while still being easy for a client to inspect. The callback wrapper validates input, runs the handler, and converts exceptions into tool-level errors.

Here’s the part that captures that flow:

function buildToolCallback(name: string, spec: ToolSpec) {
  return async (input: unknown) => {
    const parsed = z.object(spec.inputSchema).parse(input);
    try {
      const data = await spec.handler(parsed);
      return structuredPayload(name, data);
    } catch (error) {
      return errorResponse(name, error);
    }
  };
}

What I like about this approach is that it keeps all the tool-specific plumbing in one place. The actual tool registrations become declarative:

define an input schema
connect it to a client method
register the tool with the MCP server

That pattern is repeated for each tool, so the file stays readable even as the server supports multiple research operations.

The client in src/sportmicro-client.ts follows the same principle. It builds a base URL, attaches the API key as Authorization: Bearer ..., and converts non-2xx responses into a custom SportmicroClientError. That gives the server a clean way to distinguish API failures from validation problems.

Project structure at a glance

The repository is intentionally small, which helps a lot when you’re working on a protocol adapter rather than a full product.

src/
  index.ts               Entry point export
  server.ts              MCP server and tool registration
  sportmicro-client.ts   Typed Sportmicro HTTP client
  test/                  Node test files

The rest of the repository supports that core:

README.md documents setup and usage
.env.example shows the required SPORTMICRO_API_KEY
package.json defines the TypeScript build and Node test flow
docs/devto.md contains an article draft for the project

The entry point is also minimal. src/index.ts just re-exports runServer, and the server starts with stdio transport when executed directly. That is exactly what I want for MCP: a small executable surface, not a lot of bootstrapping code.

Testing and local setup

The repository supports a simple local workflow:

Node.js 20 or newer
SPORTMICRO_API_KEY in the environment
npm install
npm run build
npm test
node dist/index.js

Those commands are backed by the project files, so this isn’t speculative setup. The tests use Node’s built-in test runner and are wired to compile before execution through pretest, which means the compiled output is what gets tested.

The tests are also practical. They don’t try to hit the live Sportmicro API. Instead, they verify two things the repository can reliably check on its own:

malformed tool input is rejected before any client call
upstream Sportmicro errors are turned into actionable tool responses

That gives confidence in the contract without depending on network availability or external fixtures.

Challenges and trade-offs

I’d frame this project more as a set of design constraints than a story of runtime surprises. The code clearly reflects a few trade-offs I had to make:

Read-only by design: useful for research, but it means the server is intentionally limited in scope.
Small tool surface: easier to trust and test, but it does not attempt to cover the full Sportmicro API.
Structured JSON text responses: simple for MCP clients to parse, though not as rich as a custom resource model.
Environment-based API key handling: secure and portable, but it requires setup before the server can run.

There’s also a subtle constraint in the client implementation: it only sends query parameters when values are present. That keeps requests tidy, but it also means the server’s schemas need to stay aligned with what the API expects. In a narrow integration like this, that’s a good trade-off because it forces clarity instead of hidden behavior.

What I’d improve next

A few next steps stand out as sensible future improvements:

add richer match-detail tools where the Sportmicro documentation supports them
include more explicit freshness metadata in tool responses
add a small integration-test harness that mocks Sportmicro responses
make the output shape even more descriptive for clients that want to inspect match data programmatically

I’d keep those improvements aligned with the same principle as the current implementation: only add what can be documented, validated, and supported cleanly.

Takeaway

What I like most about this project is that it treats an MCP server as an integration boundary, not a feature dump. The server is small on purpose, the validation is explicit, and the Sportmicro client owns the API details cleanly. That makes the code easier to trust, easier to test, and easier to extend without breaking the contract.

If you’re building a TypeScript MCP server for an external API, this is the pattern I’d recommend: keep the tool surface narrow, validate early, return structured errors, and let the provider client handle the HTTP mechanics. For a read-only football fixture research server, that combination is enough to stay focused while still being useful.

How to Build a NBA Game Odds Monitor with Sportmicro

Miheve — Fri, 18 Sep 2026 20:12:35 +0000

I built this project because sports data demos often look fine in a screenshot and then fall apart the moment the API response is missing a field, the key is absent, or the data simply hasn’t arrived yet. The goal here was narrower and more useful: create a clean NBA game odds monitor that shows how to wire Sportmicro into a React + TypeScript app without hiding the messy parts of real API usage.

The repository is a small but practical example of a nba game odds monitor API workflow. Instead of trying to mimic a full sportsbook, I focused on a developer-facing dashboard that can fetch bookmaker odds, compare markets, refresh on demand, and make loading/error/empty states obvious. That makes it a better learning artifact than a “happy path only” demo.

View the repository

What I set out to build

The project is intentionally scoped around basketball odds data. In the current implementation, the app uses a dedicated Sportmicro client and a React UI to display moneyline odds and bookmaker metadata. The repository README and source show that the app currently centers on:

/odds/bookmakers
/odds/moneyline

That focus matters. A sports data API can expose a lot of surface area, but a useful tutorial usually does better when it shows one complete flow end to end rather than a half-dozen endpoints superficially.

I also wanted the structure to feel production-style even though the app is small. That means:

the UI does not build API URLs directly
the API key is read from environment variables
the app handles loading, empty, and error states explicitly
the response is normalized into a local UI-friendly shape

Those choices keep the demo honest. They also make it easier to extend later without rewriting the whole app.

Architecture: keep the Sportmicro boundary isolated

The cleanest part of the codebase is the separation between the UI and the provider-specific client. The data flow is straightforward:

UI -> app state -> Sportmicro client -> network request -> Sportmicro API

That boundary is implemented in src/sportmicroClient.ts, while src/App.tsx stays focused on state and rendering. I think that split is the right default for any sports developer API integration because it prevents the component tree from becoming a pile of fetch logic and URL assembly.

The client module does three important things:

It chooses a base URL, defaulting to https://basketball.sportmicro.com.
It reads SPORTMICRO_API_KEY from the environment.
It wraps fetch calls into typed helpers.

Here’s the core pattern:

const DEFAULT_BASE_URL = 'https://basketball.sportmicro.com';

function getBaseUrl() {
  return import.meta.env.VITE_SPORTMICRO_BASE_URL || DEFAULT_BASE_URL;
}

async function requestJson<T>(path: string, params?: Record<string, string | undefined>): Promise<T> {
  const apiKey = import.meta.env.SPORTMICRO_API_KEY as string | undefined;
  if (!apiKey) {
    throw { message: 'SPORTMICRO_API_KEY is not set. Add it to your environment before refreshing odds.' } satisfies ApiError;
  }

  const response = await fetch(buildUrl(path, params), {
    headers: { Authorization: `Bearer ${apiKey}` }
  });

  if (!response.ok) {
    throw { message: `Sportmicro request failed with HTTP ${response.status}.`, status: response.status } satisfies ApiError;
  }

  return (await response.json()) as T;
}

The important part is not the syntax; it’s the decision to make the API client the only place that knows about auth headers, base URLs, and response checking. The React app only consumes fetchBookmakers() and fetchOddsForMatch().

That keeps the integration flexible. If I later wanted to add caching, a backend proxy, or a different provider-compatible base URL, the UI would not need to know.

Implementation flow in the UI

The main application logic lives in src/App.tsx, and the flow is deliberately simple.

First, the app loads bookmaker metadata on mount:

useEffect calls fetchBookmakers()
the result populates a local bookmakers state array
if that request fails, the app quietly leaves the filter list empty

Then the user enters a match ID and clicks refresh. The refresh handler checks whether a match ID exists before calling Sportmicro. If the field is empty, the app sets a visible error and stops early.

That guard is a small but important detail. It keeps the app from pretending it can load odds without the one input it actually needs.

After the fetch succeeds, the app normalizes each odds row into a presentation-friendly shape. The normalization happens in a local helper:

function normalizeMarket(row: OddsMarket, index: number): MarketRow {
  return {
    key: [row.bookmaker_id ?? row.bookmaker_name ?? 'unknown', row.market_name ?? 'moneyline', row.selection ?? 'selection', index].join(':'),
    bookmaker: row.bookmaker_name ?? row.bookmaker_id ?? 'Unknown bookmaker',
    market: row.market_name ?? 'Moneyline',
    selection: row.selection ?? 'Unknown selection',
    odd: typeof row.odd === 'number' ? row.odd.toFixed(2) : row.odd ?? '—',
    live: row.is_live ? 'Live' : 'Pre-match',
    updatedAt: row.updated_at ?? 'Unknown'
  };
}

I like this pattern because it does two jobs at once:

it shields the UI from missing API fields
it creates a consistent display model for the table

That’s especially useful with sports data, where the provider may return optional values or varying response shapes. By the time data reaches the table, the app has already decided what “missing” should look like: Unknown, —, or a fallback label.

The UI then uses a single table to display bookmaker, market, selection, odd, state, and updated timestamp. A filter dropdown lets me narrow the view by bookmaker name. That filter is driven by the bookmaker list loaded from Sportmicro, which makes the UI feel connected to the same data source rather than acting like a static mockup.

Project structure at a glance

The tree is compact enough to understand quickly:

src/
  App.tsx             React UI and local state
  sportmicroClient.ts  Sportmicro API client and request helpers
  types.ts             Shared TypeScript types
  main.tsx             React entry point
  styles.css           Global styles

The rest of the repository supports that core flow with Vite, TypeScript, Tailwind config, and test setup. Nothing in the tree feels decorative. Each file has a clear job.

The TypeScript models are intentionally small too:

ApiError
OddsMarket
Bookmaker
MarketRow

That is a sensible choice for a focused odds monitor. I don’t need to model every possible Sportmicro basketball field to make the UI useful. A smaller type surface also makes the tutorial easier to follow, because the app only carries the data it actually renders.

Local setup and how I verified the project shape

The repository supports local development with standard Node tooling. The README documents the expected flow:

npm install
copy .env.example to .env
set SPORTMICRO_API_KEY
run npm run dev
optionally run npm run build and npm run test

That matches the scripts in package.json, which include dev, build, preview, and test.

The setup details matter because the client expects SPORTMICRO_API_KEY to exist before odds can be refreshed. The repository also documents an optional VITE_SPORTMICRO_BASE_URL, which is useful if you want to point the client at a compatible base URL during development.

I also like that the test coverage is modest and honest. The existing test in src/app.test.tsx checks that the app renders the title and the empty state. That may sound small, but it proves the shell of the experience works before any data arrives. For a demo focused on API integration, that is a meaningful baseline.

Challenges and trade-offs

I didn’t treat this project as a place to simulate dramatic failures or invented incidents. The real design constraints are more interesting.

The first trade-off is scope. The app focuses on odds comparison and refresh, not on every Sportmicro basketball endpoint. That keeps the example readable, but it also means the UI is intentionally not a complete sports platform.

The second trade-off is client-side simplicity. The current implementation uses a browser-based client with an environment-provided API key and no server proxy. That makes the demo easy to run and understand, but it also leaves room for future work if stronger credential protection or caching is needed.

The third trade-off is normalization. The app maps provider fields into a smaller MarketRow shape. That keeps rendering predictable, though it means the UI is not trying to preserve every upstream field exactly as returned.

Those are all sensible decisions for an educational repository. They reduce complexity without pretending the problem is simpler than it is.

What I would improve next

A few next steps stand out naturally from the current codebase. I would treat these as future improvements, not existing behavior:

Add another documented odds endpoint and reuse the same client pattern.
Introduce stronger row normalization if more markets are displayed.
Add deduplication based on stable provider IDs if the response shape supports it.
Consider a backend proxy if the app ever needs stricter key handling.
Add caching or a simple refresh policy if repeated requests become expensive.
Expand tests around error handling and filtering behavior.

Those changes would fit the existing architecture well because the provider boundary is already isolated. The point is not to rewrite the app; it is to extend the same pattern carefully.

Takeaway

The main lesson from this build is that a useful sports API demo is less about flashy UI and more about boundaries, fallback states, and a small amount of disciplined normalization. By keeping Sportmicro integration in one client module, using a compact TypeScript model, and making the empty/error/loading states explicit, the app stays understandable even when the data is dynamic.

If I were building another sports developer API example, I’d keep this same recipe: one provider boundary, one clear user action, one narrow data shape, and a UI that tells the truth when the data is not ready yet. That is what makes a demo feel reusable instead of disposable.

How to Build a Fantasy Football App Starter with Next.js

Miheve — Tue, 15 Sep 2026 09:11:07 +0000

How to Build a Fantasy Football App Starter with Next.js

Fantasy football is one of those ideas that sounds simple until you actually start wiring it to real sports data.

You need player lists, teams, fixtures, statistics, and a UI that can survive missing fields or temporarily unavailable endpoints. That is exactly why I like starter kits: they reduce the amount of architectural decision-making you need to do before you can ship something useful.

In this walkthrough, I built a Fantasy Football Starter Kit with Next.js, React, TypeScript, and Tailwind CSS, powered by the Sportmicro football API. The goal is not to create a complete commercial fantasy platform. Instead, the project is meant to be a practical foundation for developers who want to explore a Fantasy Football API integration without starting from zero.

The source code is available here: https://github.com//sportmicro-fantasy-football-starter-kit

For API reference, see the Sportmicro documentation: https://docs.sportmicro.com/

Why build a starter kit instead of a full platform?

A full fantasy product usually needs authentication, leagues, user management, drafts, transfers, scoring rules, live updates, and a lot of business logic. That is a big project.

A starter kit is more valuable when you want to:

validate an idea quickly
learn how a football data API behaves
prototype a UI around player statistics
experiment with fantasy points calculations
create a foundation you can grow later

This repository keeps the scope deliberately small so the architecture stays understandable.

What the project includes

The app shows a few core fantasy-football building blocks:

football player listing
player cards
team information
upcoming fixtures
player statistics
fantasy squad builder
selected team view
an example fantasy points calculation
responsive layout patterns

It is designed to feel like a real developer starting point, not a polished consumer product.

Sportmicro integration

Sportmicro provides the football data. In this starter kit, the API client is intentionally compact and only uses documented endpoints from the supplied reference.

The current client fetches:

/players
/teams
/matches-by-date
/players-statistics

That means the code demonstrates a realistic integration pattern without inventing endpoints or pretending to support features that are not in the docs.

A nice detail from a reliability standpoint is the fallback pattern. If a request fails, the app can still render using local sample data. That is useful during development and also helps communicate to users that the app is a starter kit, not a locked-down production system.

A simple API client pattern

I like to keep the API client in one place so the rest of the app can stay focused on UI composition.

The core idea is:

build a URL from the Sportmicro base URL
add query parameters only when needed
send the request with fetch
return JSON on success
throw on non-OK responses
fall back to local data in the page layer when needed

That pattern makes it easy to add more documented endpoints later.

Example request helper

async function requestJson(path: string, params = {}) {
  const url = new URL(path, baseUrl);
  // append params
  const response = await fetch(url.toString());

  if (!response.ok) {
    throw new Error(`Sportmicro request failed: ${response.status}`);
  }

  return response.json();
}

The exact production code in the repository also wires the SPORTMICRO_API_KEY environment variable through request headers so credentials never need to be hardcoded.

Environment configuration

The repo includes an .env.example file so developers know what to configure locally.

SPORTMICRO_API_KEY=
SPORTMICRO_API_BASE_URL=https://football.sportmicro.com

That is a small but important habit: starter kits should make setup obvious before they make anything flashy.

Fantasy points calculation

A fantasy app is not useful until it can translate football data into points. The repository includes a tiny scoring function that weights goals, assists, ratings, and cards.

This is intentionally simple.

Why? Because the point is to show where scoring logic lives, not to pretend there is one universal fantasy scoring system.

If you want to extend the starter kit, you could replace the scoring function with:

a league-specific rule set
custom captain bonuses
lineup constraints
position-based scoring
live match adjustments

UI structure

The app uses reusable React components so you can grow the project without rewriting the page from scratch.

For example:

PlayerCard renders individual footballers
SquadBuilder renders the selected squad area
the page composes the overall dashboard experience

That separation makes it easier to add search, filters, sorting, or saved squads later.

What I would improve next

The most obvious next steps are:

real player search input
position filtering controls
selectable squad state
match-centered projections using Sportmicro’s documented projection endpoints
pagination and caching improvements
stronger empty-state UI

If you are working with live sports data, one thing worth paying attention to is consistency across paginated endpoints. Data can shift while a user browses, so client-side handling matters.

Lessons learned

A few practical lessons from building this starter:

small API clients are easier to trust
fallback data keeps the app runnable
reusable components make the UI easier to extend
starter kits are more helpful when they show structure, not just screenshots
it is better to build around documented endpoints only

Closing thoughts

If you want a football data API example that is easy to read and extend, a starter kit is a great place to begin. Sportmicro fits that approach well because it provides a broad football data surface, and the repo can stay focused on integration patterns rather than trying to solve every fantasy feature at once.

If you want to explore the project, start here:

GitHub: https://github.com//sportmicro-fantasy-football-starter-kit
Sportmicro: https://sportmicro.com
Docs: https://docs.sportmicro.com/

And if you build on it, keep the scope honest. The best starter kits are the ones that help the next developer move quickly without hiding the hard parts.

Building Real-Time Sports Apps with WebSockets with Sportmicro

Miheve — Thu, 10 Sep 2026 00:51:57 +0000

I built this project because I wanted a clean, practical way to show how a sports app can feel live without turning the browser into a data-fetching liability.

That’s the core tension with real-time sports experiences: users expect scores and events to update instantly, but frontend code should never carry private API credentials. So the shape of the solution became clear pretty quickly. I needed a browser UI, a Node.js relay, and a sports data source that could feed live updates into the relay. That’s where Sportmicro fit naturally.

The result is a small but complete demo: a React client connects to a local WebSocket server, the server talks to Sportmicro on the backend, and the browser gets normalized snapshots of live matches and event-style updates. The UI never needs to know anything about the upstream authentication layer. If you want to inspect the code, View the repository.

The problem I was solving

I wanted the demo to answer a very specific question: how do you build a sports WebSocket API experience that feels real-time while keeping the architecture safe and understandable?

That immediately ruled out the simplest approach of calling a sports API directly from the browser. It might be convenient, but it puts secrets in the wrong place. Instead, I built the app around a backend relay pattern. The browser only opens a WebSocket to my local server. The server uses SPORTMICRO_API_KEY to fetch data from Sportmicro’s documented endpoints and then forwards the result back to the UI.

That architecture is small enough to understand in one sitting, but it still mirrors how I’d structure a real-time sports dashboard in production.

The architecture in plain English

There are three moving parts:

React client — handles the UI, sport selection, and connection state.
Node.js WebSocket server — accepts browser connections and relays data.
Sportmicro — provides the sports data from documented REST endpoints.

The client and server communicate with a tiny message schema. The browser sends a subscribe message when a sport is selected. The server responds with connection, snapshot, or error messages. That keeps the flow predictable and makes the UI logic straightforward.

The supported sports in this demo are:

football
basketball
tennis

In the repository, that shows up in the shared types and the sport option lists. I like this kind of setup because it keeps the interface honest: the UI only exposes what the backend and the data model actually support.

Why the relay pattern mattered

This is one of those cases where the architecture is the feature.

A browser app can absolutely open WebSockets, but it should not hold private API keys. The relay solves that by moving all upstream Sportmicro access into the Node server. That gives you a few useful properties:

credentials stay server-side
the upstream response can be normalized before the client sees it
reconnect and error handling can live in one place
the frontend stays focused on rendering

That last point matters more than people think. Once the browser is only responsible for UI state, the code becomes much easier to reason about. The app becomes a consumer of snapshots instead of a mini data platform.

How Sportmicro fits into the flow

The project documentation and README make one thing clear: this demo uses documented Sportmicro endpoints only. The backend demonstrates live match retrieval and live incident-style event retrieval, with tennis using a point-by-point style fallback for incident-like updates.

The important part is not the exact endpoint syntax. It’s the pattern: the Node server fetches live sports data from Sportmicro, transforms it into a small application-specific snapshot, and pushes that snapshot over WebSocket.

That snapshot contains:

the selected sport
a fetch timestamp
a list of matches
a list of incidents

The UI then renders those two lists in separate panels: one for live match cards and one for the event log. It’s a simple model, but it’s enough to demonstrate live scores WebSocket behavior without pretending the app is doing more than it is.

Implementation flow

I like to think of the implementation as four layers: types, transport, data shaping, and presentation.

1. Define the shared message contract

The src/types.ts file is doing a lot of quiet work. It defines the allowed sport values, connection states, match records, incident records, and the client/server message types.

That pays off immediately in a project like this. The frontend hook knows what a snapshot looks like, and the app component knows what it can expect from the data. That gives the demo a strong spine without any unnecessary complexity.

2. Build the WebSocket hook

The useSportStream hook in src/websocket/useSportStream.ts is the client’s communication layer.

Its responsibilities are intentionally narrow:

connect to the WebSocket URL
send a subscribe message when the socket opens
listen for snapshot and error messages
handle reconnects after disconnects

I especially like the reconnection approach here because it’s practical but not overengineered. If the socket closes unexpectedly, the hook marks the state as reconnecting and tries again after a short delay. If the component unmounts, it stops reconnecting and closes the socket cleanly. That’s exactly the kind of behavior you want in a sports data streaming demo: resilient, but not noisy.

3. Shape the UI around live state

The App.tsx component is where the project becomes visible.

It keeps the selected sport in local state, passes that into useSportStream, and then renders three main areas:

a hero section with the project framing
a toolbar with sport selection and connection state
a two-column content area with matches and events

The match rendering includes a few thoughtful details:

a helper to build a human-readable title
a helper to format score lines
a fallback empty state when there are no live matches

That last point is important. Real sports APIs often return empty results depending on timing, match availability, or the selected sport. A demo should acknowledge that instead of faking content.

The event log follows the same principle. It renders recent incident records if they exist, otherwise it shows a clear empty state. That keeps the app truthful in local development.

4. Keep the server as the secure middle layer

The server files are the part of the app I’d expect another engineer to extend first.

The repository includes a Node server entry point and a Sportmicro integration module. The README describes the server’s job clearly: accept WebSocket connections, authenticate with Sportmicro using SPORTMICRO_API_KEY, fetch data from documented endpoints only, and stream normalized snapshots back to the browser.

That’s the right boundary. The frontend never knows about the API key, and the backend never leaks raw upstream details into the UI unless the app deliberately chooses to render them.

A quick look at the structure

Here’s the shape of the project as it stands:

.
├── server/
│   ├── index.ts
│   └── sportmicro.ts
├── src/
│   ├── App.tsx
│   ├── App.test.tsx
│   ├── main.tsx
│   ├── styles.css
│   ├── sportLabels.ts
│   ├── sports.ts
│   ├── types.ts
│   └── websocket/
│       └── useSportStream.ts
├── .env.example
├── README.md
├── package.json
└── vite.config.ts

That tree tells the whole story: a small server, a focused React app, and shared types that keep the transport contract explicit.

What I liked about the implementation choices

There are a few design decisions here that make the project feel well-scoped.

First, the app only supports three sports, and that’s enough. I’ve seen too many demos get cluttered by trying to support everything at once. A constrained set of options makes the architecture easier to understand.

Second, the client and server each have a single job. The React side renders state. The Node side manages the socket bridge and upstream access. That division keeps the code readable.

Third, the UI acknowledges uncertainty. If there are no live matches or no event records, the screen doesn’t pretend otherwise. That makes the demo more credible and a better foundation for future expansion.

Fourth, there’s test coverage for the app’s basic rendering. The included test checks that the headline, Sportmicro branding, and connected state appear as expected when the hook is mocked. That’s a sensible unit boundary for a project like this.

Local setup, based on the repository docs

The repository documents a straightforward local setup:

Node.js 18+ is required
an active Sportmicro API key is needed
dependencies are installed with npm install
.env.example is copied to .env
the app is started with npm run dev
the client can be built with npm run build:client
the full production build uses npm run build

The documented environment variables are:

SPORTMICRO_API_KEY
PORT
CLIENT_ORIGIN
VITE_WS_URL

I appreciate that the repository is explicit about these pieces. For a real-time demo, environment variables are not just config; they’re part of the architecture.

Sensible next improvements

If I were extending this project, I’d keep the same architecture and improve it incrementally.

A few natural next steps stand out:

add clearer loading states for each sport transition
surface richer metadata in the match cards if the upstream response supports it
improve the event log grouping or ordering
make the empty states more sport-aware
add more tests around socket state changes and error rendering

I’d also keep an eye on the boundary between normalization and presentation. The backend should continue shaping upstream data into a consistent snapshot, so the frontend stays simple even if new Sportmicro endpoints are added later.

That matters because once a live sports app starts growing, the temptation is to let every new upstream field leak straight into the UI. This demo avoids that trap by starting with a stable message contract.

What I took away

The biggest lesson from this build is that real-time doesn’t have to mean complicated.

If you keep the data flow small, define a clear WebSocket message contract, and place the API boundary on the server, you can build a convincing live sports experience without overengineering it. The result is a practical pattern for a Sportmicro powered sports dashboard: the browser subscribes, the server relays, and the UI updates as soon as new snapshots arrive.

That’s the part I’d want another developer to remember. The magic of a sports WebSocket API app is not that every piece is advanced. It’s that each piece does one job well, and the whole system feels live because the flow is simple, secure, and explicit.

How to Build a Football Odds Tracker with React

Miheve — Sun, 30 Aug 2026 11:29:16 +0000

If you have ever tried to build a football odds dashboard from scratch, you know the first challenge is not the UI — it is the data shape. Fixtures, bookmakers, markets, and kickoff times all arrive with enough optionality to make a simple prototype feel fragile fast. I wanted to build something practical: a small tracker that compares upcoming matches and odds without turning into a pile of ad hoc fetch calls.

That is what led me to this project, a React + TypeScript app that uses Sportmicro as the data source for football odds and match data. The result is intentionally modest, but that is the point. It shows the path from a typed frontend to a usable odds comparison interface, while keeping the implementation clean enough to extend later.

View the repository

What I set out to solve

The app is built around a simple question: how do I present football odds in a way that is readable, resilient, and easy to refresh?

A lot of sports data demos stop at rendering a list of fixtures. That is fine for a proof of concept, but the more useful version is one that also shows bookmaker odds, handles missing values gracefully, and gives the user a way to filter the noise. I wanted the experience to feel like a lightweight sportsbook-style dashboard rather than a static API sample.

So the project focuses on a few specific outcomes:

upcoming football matches
league and competition details
home and away teams
kickoff times
bookmaker odds for the full-time result market
a simple league filter
a manual refresh action
loading and error states
fallback sample data when live requests fail

That scope is narrow on purpose. It makes the app easier to reason about, and it matches the idea of using Sportmicro as the backend for football analytics, betting, or sportsbook interfaces.

Why Sportmicro fits the architecture

The project uses the Sportmicro football API directly from the frontend, with a dedicated client in src/apiClient.ts. The app only relies on two documented endpoints:

GET /matches
GET /odds/full-time-results

That was enough to build the core experience. The match endpoint provides upcoming fixtures, and the odds endpoint supplies bookmaker prices for the full-time result market. Those two data sources complement each other well: one gives structure, the other gives context.

I also like the fact that the app treats the API as an external dependency rather than assuming it will always be available. The code expects data to be incomplete or temporarily unavailable, which is exactly how sports data behaves in real projects. The UI therefore leans on local sample data when requests fail, rather than leaving the page blank.

The API base URL used in the project is https://football.sportmicro.com, and the repository also points to the Sportmicro docs as the source of truth for endpoint behavior. That discipline matters. When you build on a sports betting API, the safest approach is to request only what you need and model only the fields you actually render.

The project structure I worked with

The repository is intentionally compact. The core files are easy to map mentally:

src/
  App.tsx
  apiClient.ts
  main.tsx
  mockData.ts
  styles.css
  types.ts
  test/

That structure is simple, but it covers the main layers of the app:

apiClient.ts isolates Sportmicro requests
types.ts defines the local data model
mockData.ts provides sample matches, leagues, and odds
App.tsx handles the user interface and data flow
main.tsx mounts the React app
test/ contains tests for the client and shell rendering

This separation is what keeps the project understandable. I do not need to hunt through UI code to see how requests work, and I do not need to inspect fetch logic to understand how the screen behaves.

The implementation flow

The app starts in src/main.tsx, where React renders the root App component and loads styles.css. Nothing unusual there, which is a good sign. The important work happens inside App.tsx.

1) I defined the data model first

The TypeScript interfaces in src/types.ts keep the app grounded in the fields the UI actually needs:

League has an id and name, with a couple of optional metadata fields
Match includes league ID, league name, team names, start time, status, and bookmaker count
FullTimeResultOdds represents odds for a single match and bookmaker
each outcome can carry a name and an optional price

That design keeps the UI flexible. It does not assume every field will be present, and it lets the interface degrade gracefully if the API returns partial data.

2) I centralized requests in one helper

The request helper in src/apiClient.ts is small, but it does the important things:

it builds URLs against the Sportmicro football API base
it appends query parameters in a reusable way
it sends an Accept: application/json header
it adds a Bearer token when SPORTMICRO_API_KEY is available
it throws a typed SportmicroApiError when the response is not OK

That error class is useful because the UI can distinguish a known API failure from some other unexpected issue. In practice, that means the app can give a helpful message and fall back to sample data instead of crashing.

3) I used local sample data as a safety net

The mock data in src/mockData.ts includes a few leagues, matches, and odds records. This is not a fake product layer; it is a fallback layer.

That fallback is important for two reasons:

it keeps the app useful when live API requests fail
it makes the interface easier to understand before a real API key is configured

I think that is the right tradeoff for a public demo. A sports app without data is not very convincing, and a sports app that breaks when the backend is offline is not very trustworthy.

4) I built the refresh flow around live requests

The refreshData function in App.tsx is the main data-loading path. It sets a loading state, clears previous errors, and then requests both /matches and /odds/full-time-results.

If the requests succeed:

live matches replace the current match list
live odds replace the current odds list
empty responses fall back to sample data

If the requests fail:

the app shows a clear message
sample data is restored
the interface stays usable

That behavior is probably the most practical part of the project. It lets the app act as both a demo and a real-time tracker without forcing the user into a broken state.

5) I added filtering and visual separation

The interface has a simple league filter powered by local state. It filters the displayed matches by league_id, with an all option for the full list. It is a small interaction, but it makes the screen more useful immediately.

The odds are rendered in a separate section via a dedicated OddsCard component. I like this split because fixtures and market data are related, but they are not the same thing. Separate cards make that distinction clearer.

The render logic also deals with partial values carefully:

Time unavailable when kickoff time is missing
Competition unavailable when the league name is absent
N/A for missing odds prices
upcoming when a status is not provided

That kind of defensive rendering is easy to overlook, but it is exactly what makes a tracker feel reliable.

What the UI is doing well

The app is not trying to imitate a full sportsbook. Instead, it stays focused on a few useful views:

a header that explains the purpose
a manual refresh button
a league filter sidebar
match cards for upcoming fixtures
odds cards for the full-time result market
an API usage note at the bottom

The layout is responsive, and the styling is handled with Tailwind CSS. That keeps the code concise while still making the interface readable on different screen sizes.

I also appreciate that the app surfaces its data source clearly. The “Powered by Sportmicro” text and the docs link are a nice reminder that this is a live-data application, not a static mock.

Testing the core pieces

The repository includes tests for the API client and for the app shell.

The API client test checks two important behaviors:

it builds the correct request URL
it throws a typed error when the response is not OK

That gives confidence that the Sportmicro integration layer behaves as expected.

The app test renders the shell and verifies that the main structure is present. That is a sensible lightweight test for this kind of project. It does not overreach, but it protects the core user-facing layout.

Local setup, based on the repository

The repository includes a standard Vite setup and documents a straightforward local workflow:

npm install
npm run dev
npm run build
npm run test

It also expects a local .env file based on .env.example, with SPORTMICRO_API_KEY set for authenticated requests.

That is enough to run the project locally, and the README makes it clear that the app can still operate with sample data if the API is unavailable. I did not need anything more elaborate than that to understand how to get started.

Sensible next improvements

Because the project is already small and focused, the next improvements should stay grounded in the same design.

A few directions make sense:

add more documented Sportmicro views, such as leagues, standings, teams, or matches by date
expand the odds display beyond the full-time result market if the documentation supports it
make the filter controls richer without adding clutter
improve empty-state messaging for fixtures and odds separately
keep extending the test coverage around request handling and rendering paths

The important thing is to keep the same pattern: typed data model, centralized API client, and UI that assumes data can be partial or unavailable.

Takeaway

What I like about this project is that it treats a football odds app as a real engineering exercise, not just a data display exercise. The combination of React, TypeScript, Vite, and Sportmicro gives you a clean path to build a useful sportsbook-style interface, but the real lesson is architectural: isolate the API, type the data you consume, and never assume live sports data will be complete.

If you are building a football odds tracker, that mindset matters more than any individual component. Start with the smallest useful slice, keep the integration clean, and let the UI fail gracefully. That is what makes a demo worth keeping around after the first run.

I Built a Football Livescore App That Still Works Without an API Key

Miheve — Sun, 14 Jun 2026 14:34:44 +0000

A football livescore app looks simple until you try to build one properly.

At first, the idea was straightforward:

show live matches
let users browse fixtures by date
organize games by league
add a match details page
display team and competition logos

But once I started building it, the real challenge was not rendering a score.

The harder part was deciding how the data layer should behave when:

the API key is missing
the external API is unavailable
the response shape changes
a team logo does not exist
the UI needs to work before the live integration is ready

That led me to build PitchPulse Live, a production-style football livescore application using Next.js, TypeScript, Tailwind CSS, and SportMicro football data.

The part I like most is that the application does not become unusable when no API key is configured.

It automatically switches to mock data.

This means someone can clone the repository, run the app, explore the interface, and continue development without first setting up access to an external sports API.

Repository:

github.com/mihailove123/pitchpulse-livescore-ap

What I Wanted to Build

I did not want the project to be only a page with several hardcoded match cards.

The goal was to create a small but realistic football product with a structure that could later support more advanced features.

The first version includes:

a live match scoreboard
daily fixture browsing
league filtering
a league directory
individual match pages
team and league logos
server-rendered data fetching
automatic mock fallback

The main routes are:

/               Live matches and daily fixtures
/leagues        Football league directory
/matches/[id]   Match details

The app is built with the Next.js App Router.

That allowed me to keep the initial data fetching on the server while still using interactive client components for date selection and league filtering.

The Stack

The project uses:

Next.js 16
React 19
TypeScript
Tailwind CSS 4
SportMicro Football API
@sportmicro/endpoint

The project structure looks like this:

src/
  app/
    page.tsx
    leagues/
      page.tsx
    matches/
      [id]/
        page.tsx

  components/
    EntityLogo.tsx
    MatchCard.tsx
    MatchList.tsx
    LeagueFilter.tsx
    DateSelector.tsx

  lib/
    sportmicro.ts
    mock-data.ts
    utils.ts

  types/
    sportmicro.ts

public/
  screenshots/
    sc.png

The important design decision was to keep the football data logic separate from the UI.

The pages should not need to know how authentication headers are created, how query parameters are built, or how raw API responses are normalized.

They should only receive app-friendly objects and render them.

The First Problem: External Data Should Not Control the Entire App

When building an API-powered interface, it is tempting to connect the UI directly to the raw response.

For example:

<div>
  <span>{match.home_team?.name}</span>
  <span>{match.score?.home}</span>
  <span>{match.score?.away}</span>
  <span>{match.away_team?.name}</span>
</div>

This works initially, but it creates a tight dependency between the interface and the external API.

If the API changes a field name, every component using that field may need to change.

Instead, PitchPulse normalizes the responses inside the data layer.

The UI consumes internal types such as:

export type FootballMatch = {
  id: string
  homeTeam: {
    id: string
    name: string
    logo?: string
  }
  awayTeam: {
    id: string
    name: string
    logo?: string
  }
  homeScore: number | null
  awayScore: number | null
  status: string
  startTime: string
  league: {
    id: string
    name: string
    logo?: string
  }
}

This creates a useful boundary:

External API response
        ↓
Normalization layer
        ↓
Application types
        ↓
React components

The components no longer care where the data came from.

That becomes especially useful because the same components can render both live API data and local mock data.

Using `@sportmicro/endpoint` as a Query Builder

The project uses the @sportmicro/endpoint package, but not as a full API client.

I use it to construct PostgREST-style endpoint paths.

For example:

const path = endpoint("matches")
  .property("status_type")
  .equals("live")
  .select(
    "id",
    "start_time",
    "status_type",
    "home_team",
    "away_team",
    "home_score",
    "away_score"
  )
  .limit("12")
  .order((order) =>
    order.property("start_time").ascending
  )
  .toString()

The package handles the query structure.

The application still sends the actual HTTP request with fetch.

const response = await fetch(
  `${FOOTBALL_API_URL}/${path}?lang=en`,
  {
    headers: {
      Authorization: `Bearer ${SPORTMICRO_API_KEY}`,
      Accept: "application/json",
    },
    next: {
      revalidate: 30,
    },
  }
)

I like this approach because it keeps endpoint construction readable.

Instead of manually building a long query string:

const url =
  "/matches?status_type=eq.live&select=id,start_time,status_type..."

the code describes the query step by step.

One Wrapper for All Football Requests

The SportMicro integration lives in:

src/lib/sportmicro.ts

That file is responsible for:

building endpoint paths
attaching the API key
sending requests
handling errors
switching to mock data
normalizing responses

The rest of the application calls functions such as:

getLiveFootballMatches()
getFixturesByDate(date)
getMatchDetails(matchId)
getLeagues()

A page does not need to know which endpoint is being used.

export default async function HomePage() {
  const liveMatches =
    await getLiveFootballMatches()

  const fixtures =
    await getFixturesByDate(today)

  return (
    <main>
      <MatchList matches={liveMatches} />
      <MatchList matches={fixtures} />
    </main>
  )
}

This keeps the page focused on presentation.

The transport logic remains in one place.

Why I Added Mock Mode

The mock fallback became one of the most useful parts of the project.

Normally, an API-powered repository creates friction for anyone trying to run it.

They clone the project, install the dependencies, and immediately see an error:

Missing API key

That is not a great first experience.

In PitchPulse Live, the application checks whether the environment variable exists.

const apiKey = process.env.SPORTMICRO_API_KEY

const isMockMode = !apiKey

When the key is missing, the data functions return local sample data.

export async function getLiveFootballMatches() {
  if (isMockMode) {
    return mockLiveMatches
  }

  return fetchLiveMatchesFromApi()
}

That means the setup can be as simple as:

git clone https://github.com/mihailove123/pitchpulse-livescore-ap.git

cd pitchpulse-livescore-ap

npm install

npm run dev

No external account is required to inspect the layout.

No secret needs to be configured to work on the components.

The live integration can be enabled later by creating .env.local:

SPORTMICRO_API_KEY=your_sportmicro_api_key_here

This creates two useful development modes.

Mock mode
  UI development
  component testing
  layout work
  demos
  local onboarding

Live mode
  real scores
  real fixtures
  real leagues
  real match details

The same UI works in both modes because both data sources are normalized into the same types.

Making Missing Logos Look Intentional

Football data is rarely perfectly complete.

Some teams have logos.

Some do not.

Some image URLs fail.

Some lower-level leagues may have incomplete branding.

Rendering a broken image icon makes the whole application look unfinished.

That is why I added a reusable EntityLogo component.

type EntityLogoProps = {
  name: string
  imageUrl?: string | null
}

export function EntityLogo({
  name,
  imageUrl,
}: EntityLogoProps) {
  if (imageUrl) {
    return (
      <img
        src={imageUrl}
        alt={`${name} logo`}
        className="h-10 w-10 object-contain"
      />
    )
  }

  const initials = name
    .split(" ")
    .map((word) => word[0])
    .join("")
    .slice(0, 2)
    .toUpperCase()

  return (
    <div className="flex h-10 w-10 items-center justify-center rounded-full bg-neutral-800 text-sm font-semibold">
      {initials}
    </div>
  )
}

Remote images are loaded from:

https://images.sportmicro.com/{hash}.png

If no valid image is available, the component displays initials instead.

This is a small feature, but it prevents incomplete data from damaging the interface.

The fallback looks intentional rather than accidental.

Building Reusable Match Cards

The main reusable UI unit is MatchCard.tsx.

A match card needs to support several states:

Scheduled
Live
Finished
Postponed
Cancelled

A scheduled match should emphasize kickoff time.

A live match should emphasize the score and current status.

A completed match should make it clear that the score is final.

A simplified version looks like this:

export function MatchCard({
  match,
}: {
  match: FootballMatch
}) {
  const isScheduled =
    match.status === "scheduled"

  const isLive =
    match.status === "live"

  return (
    <article className="rounded-xl border p-4">
      <div className="flex items-center justify-between">
        <Team
          name={match.homeTeam.name}
          logo={match.homeTeam.logo}
        />

        <div className="text-center">
          {isScheduled ? (
            <time dateTime={match.startTime}>
              {formatMatchTime(match.startTime)}
            </time>
          ) : (
            <strong className="text-xl">
              {match.homeScore ?? 0}
              {" - "}
              {match.awayScore ?? 0}
            </strong>
          )}

          {isLive && (
            <span className="block text-xs">
              LIVE
            </span>
          )}
        </div>

        <Team
          name={match.awayTeam.name}
          logo={match.awayTeam.logo}
        />
      </div>
    </article>
  )
}

Because the card consumes normalized match data, it can be reused on:

the homepage
fixture results
league pages
related-match sections
search results

Date and League Filtering

The homepage includes controls for browsing fixtures.

The user can select a date and narrow the list by league.

The date selector updates the requested day:

<DateSelector selectedDate={date} />

The league filter receives the competitions found in the returned fixtures:

<LeagueFilter
  leagues={availableLeagues}
  selectedLeague={leagueId}
/>

The filtering logic stays separate from the match card.

That separation matters because the match component should not decide which matches are visible.

Its job is only to render one match correctly.

Match Details as a Dynamic Route

Each match links to:

/matches/[id]

The page reads the dynamic route parameter and loads the details.

type MatchPageProps = {
  params: Promise<{
    id: string
  }>
}

export default async function MatchPage({
  params,
}: MatchPageProps) {
  const { id } = await params

  const match =
    await getMatchDetails(id)

  return (
    <main>
      <MatchHeader match={match} />
      <MatchSummary match={match} />
    </main>
  )
}

The current page displays a score snapshot and match summary.

The route is intentionally designed so it can later support:

incidents
goals
cards
substitutions
lineups
statistics
head-to-head results

That is one of the advantages of starting with a clear route and data layer rather than placing everything on one page.

Server Rendering Keeps the Pages Simple

The application uses server-rendered data fetching.

This means pages can request their data before rendering.

export default async function LeaguesPage() {
  const leagues = await getLeagues()

  return (
    <main>
      <h1>Football Leagues</h1>
      <LeagueGrid leagues={leagues} />
    </main>
  )
}

There is no initial client-side loading effect.

There is no empty page waiting for JavaScript to fetch the first result.

Interactive pieces such as the date selector can still be client components, but the initial football data is rendered on the server.

This gives the project a clean split:

Server Components
  data fetching
  page composition
  initial rendering

Client Components
  filters
  date controls
  interactive state

The Complete Data Flow

A typical request moves through the project like this:

User opens the homepage
        ↓
Next.js page calls getLiveFootballMatches()
        ↓
The helper checks for SPORTMICRO_API_KEY
        ↓
No key?
  Return normalized mock data
        ↓
Key exists?
  Build the API path with @sportmicro/endpoint
        ↓
Send the authenticated request with fetch
        ↓
Normalize the response
        ↓
Render MatchList
        ↓
MatchList renders MatchCard components

The UI never needs separate code for live and mock mode.

That is the main benefit of normalizing the data before it reaches the components.

Running the Project

Clone the repository:

git clone https://github.com/mihailove123/pitchpulse-livescore-ap.git

Enter the project:

cd pitchpulse-livescore-ap

Install dependencies:

npm install

Run the development server:

npm run dev

Open:

http://localhost:3000

The application will automatically run with sample data.

To enable live football data, create:

.env.local

Add:

SPORTMICRO_API_KEY=your_sportmicro_api_key_here

Then restart the development server.

Available Commands

npm run dev
npm run build
npm run start
npm run lint
npm run typecheck

Before deploying, I recommend running:

npm run lint
npm run typecheck
npm run build

This catches type errors and production build issues before they reach the hosting platform.

Deployment

The repository can be deployed to Vercel or another Next.js-compatible platform.

A basic deployment flow is:

Push the repository to GitHub
        ↓
Import the repository into Vercel
        ↓
Add SPORTMICRO_API_KEY
        ↓
Deploy

Mock mode can also be useful for preview deployments where live credentials should not be available.

What I Would Build Next

The current repository provides a foundation rather than every possible football feature.

The next additions could include:

league standings
match incidents
team lineups
player statistics
team pages
league-specific fixture pages
favorite teams
goal notifications
live polling
match search
user time zones

The existing structure makes these additions easier because the transport and UI layers are already separated.

New API methods can be added to:

src/lib/sportmicro.ts

New normalized types can be added to:

src/types/sportmicro.ts

The components can continue receiving predictable application objects.

What I Learned

The most important lesson from this project was not about football data.

It was about fallback design.

An API integration should not make the entire application impossible to run without the API.

By keeping mock and live data behind the same functions, the project becomes:

easier to clone
easier to test
easier to demonstrate
easier to contribute to
easier to develop offline

The second lesson was to normalize external data early.

Raw API responses are useful at the network boundary.

They should not become the language spoken by the entire application.

The final architecture is simple:

Query builder
      ↓
Authenticated request
      ↓
Normalized application data
      ↓
Reusable football components

That structure is what turns a football API demo into an application that can continue growing.

The source code is available here:

PitchPulse Live on GitHub

I would be interested to hear how other developers handle mock mode in API-powered projects. Do you keep static fixtures, use a local mock server, or make the real integration optional?

My Football App Worked Perfectly Until Matchday Started

Miheve — Sun, 14 Jun 2026 14:17:09 +0000

Building a football scores app looked easy when I first planned it.

Fetch today's matches.

Display the teams.

Show the score.

Refresh the page every few seconds.

That was the entire architecture.

During development, it worked perfectly. I tested it with a few sample matches, opened the page in two browser tabs, and watched the scores update.

Then the first busy matchday arrived.

Several games started at the same time. Hundreds of users opened the app. Requests began overlapping. Some scores appeared to move backward. Finished matches continued refreshing, and the same football data was fetched separately for every visitor.

The API was working correctly.

The frontend was rendering what it received.

The problem was everything between them.

That day taught me that a football livescore app is not simply a website connected to an API.

It is a live data synchronization system.

The First Version

My first implementation was a client-side component with a polling interval.

"use client"

import { useEffect, useState } from "react"

type Match = {
  id: string
  homeTeam: string
  awayTeam: string
  homeScore: number
  awayScore: number
}

export default function LiveMatches() {
  const [matches, setMatches] = useState<Match[]>([])

  useEffect(() => {
    async function fetchMatches() {
      const response = await fetch("/api/matches/live")
      const data = await response.json()

      setMatches(data.matches)
    }

    fetchMatches()

    const intervalId = window.setInterval(
      fetchMatches,
      5000
    )

    return () => {
      window.clearInterval(intervalId)
    }
  }, [])

  return (
    <div>
      {matches.map((match) => (
        <article key={match.id}>
          <span>{match.homeTeam}</span>

          <strong>
            {match.homeScore} - {match.awayScore}
          </strong>

          <span>{match.awayTeam}</span>
        </article>
      ))}
    </div>
  )
}

It looked reasonable.

Every five seconds, the app requested the newest scores and replaced the current state.

The problem became obvious when the number of users increased.

1 user      = 12 requests per minute
100 users   = 1,200 requests per minute
1,000 users = 12,000 requests per minute

Most of those requests were asking for exactly the same data.

Every browser was independently fetching the same matches.

The app had no shared cache, no request coordination, and no understanding of whether the matches could still change.

A Live Score Does Not Need to Be Fetched Separately for Every User

When two users open the same match page, they usually need the same score.

The score is not personalized.

That means the server should be able to reuse a recently fetched result instead of requesting the football provider again for every visitor.

A basic server-side request function might look like this:

// lib/football-api.ts

import "server-only"

const baseUrl = process.env.FOOTBALL_API_URL
const apiKey = process.env.FOOTBALL_API_KEY

if (!baseUrl) {
  throw new Error("FOOTBALL_API_URL is missing")
}

if (!apiKey) {
  throw new Error("FOOTBALL_API_KEY is missing")
}

export async function footballRequest<T>(
  endpoint: string,
  revalidate = 15
): Promise<T> {
  const response = await fetch(
    `${baseUrl}${endpoint}`,
    {
      headers: {
        Accept: "application/json",
        Authorization: `Bearer ${apiKey}`,
      },
      next: {
        revalidate,
      },
    }
  )

  if (!response.ok) {
    throw new Error(
      `Football API request failed with ${response.status}`
    )
  }

  return response.json() as Promise<T>
}

The important part is not the exact URL or authentication format.

The important part is that the external API request happens on the server.

The browser communicates with your application.

Your application communicates with the football data provider.

This gives you control over:

API credentials
Caching
Error handling
Rate limiting
Response formatting
Logging

Never Expose the Football API Key in the Browser

This is unsafe:

const response = await fetch(
  `https://example.com/live?key=${process.env.NEXT_PUBLIC_FOOTBALL_API_KEY}`
)

Variables prefixed with NEXT_PUBLIC_ can be included in client-side JavaScript.

Anyone using the application may be able to inspect the request and copy the key.

Instead, keep the key in a private environment variable:

FOOTBALL_API_URL=https://api.example.com
FOOTBALL_API_KEY=your_private_key

Then import the API client only from server-side files.

import "server-only"

A football app can generate a large number of requests during popular matches. An exposed key can quickly become expensive.

Do Not Use the Raw API Response Everywhere

My next mistake was passing the provider response directly into React components.

The component expected fields such as:

<p>{event.home_team.name}</p>
<p>{event.current_score.home}</p>
<p>{event.match_status}</p>

That created a strong dependency between the UI and one specific response format.

When one endpoint returned homeTeam instead of home_team, I had to add special cases inside the component.

A better approach is to define an internal match type.

// types/match.ts

export type MatchStatus =
  | "scheduled"
  | "live"
  | "halftime"
  | "finished"
  | "postponed"
  | "cancelled"

export type Team = {
  id: string
  name: string
  logoUrl: string | null
}

export type FootballMatch = {
  id: string
  competition: {
    id: string
    name: string
    country: string | null
  }
  homeTeam: Team
  awayTeam: Team
  score: {
    home: number | null
    away: number | null
  }
  status: MatchStatus
  minute: number | null
  startsAt: string
}

Then map the provider response into the application's format.

// lib/map-match.ts

import type {
  FootballMatch,
  MatchStatus,
} from "@/types/match"

type ApiMatch = {
  id: string | number
  status?: string
  minute?: number | null
  start_time?: string
  league?: {
    id?: string | number
    name?: string
    country?: string
  }
  home?: {
    id?: string | number
    name?: string
    logo?: string
  }
  away?: {
    id?: string | number
    name?: string
    logo?: string
  }
  scores?: {
    home?: number | null
    away?: number | null
  }
}

export function mapMatch(
  match: ApiMatch
): FootballMatch {
  return {
    id: String(match.id),
    competition: {
      id: String(match.league?.id ?? "unknown"),
      name: match.league?.name ?? "Unknown competition",
      country: match.league?.country ?? null,
    },
    homeTeam: {
      id: String(match.home?.id ?? "unknown-home"),
      name: match.home?.name ?? "Home team",
      logoUrl: match.home?.logo ?? null,
    },
    awayTeam: {
      id: String(match.away?.id ?? "unknown-away"),
      name: match.away?.name ?? "Away team",
      logoUrl: match.away?.logo ?? null,
    },
    score: {
      home: match.scores?.home ?? null,
      away: match.scores?.away ?? null,
    },
    status: normalizeStatus(match.status),
    minute: match.minute ?? null,
    startsAt:
      match.start_time ?? new Date().toISOString(),
  }
}

function normalizeStatus(
  status?: string
): MatchStatus {
  switch (status?.toLowerCase()) {
    case "live":
    case "first_half":
    case "second_half":
    case "in_progress":
      return "live"

    case "half_time":
    case "halftime":
      return "halftime"

    case "full_time":
    case "finished":
    case "ended":
      return "finished"

    case "postponed":
      return "postponed"

    case "cancelled":
    case "canceled":
      return "cancelled"

    default:
      return "scheduled"
  }
}

Now the components depend on a stable application model.

If the external API changes, only the mapping layer needs to change.

Render the First Match List on the Server

My first app displayed an empty loading screen until the browser completed its first request.

That was unnecessary.

With Next.js Server Components, the initial matches can be loaded before the page reaches the browser.

// app/page.tsx

import { MatchCenter } from "@/components/match-center"
import { getMatchesByDate } from "@/lib/get-matches"

export default async function HomePage() {
  const date = new Date()
    .toISOString()
    .slice(0, 10)

  const matches = await getMatchesByDate(date)

  return (
    <main>
      <header>
        <p>Football scores</p>
        <h1>Today's Matches</h1>
      </header>

      <MatchCenter
        date={date}
        initialMatches={matches}
      />
    </main>
  )
}

The server-side data function can apply a short cache duration.

// lib/get-matches.ts

import "server-only"

import { footballRequest } from "@/lib/football-api"
import { mapMatch } from "@/lib/map-match"
import type { FootballMatch } from "@/types/match"

type MatchesResponse = {
  matches: unknown[]
}

export async function getMatchesByDate(
  date: string
): Promise<FootballMatch[]> {
  const response =
    await footballRequest<MatchesResponse>(
      `/matches?date=${encodeURIComponent(date)}`,
      30
    )

  return response.matches.map((match) =>
    mapMatch(match as never)
  )
}

The visitor sees content immediately.

The client-side code only needs to keep that content updated.

Use Your Own Route Handler for Updates

The browser should not need to know which provider powers the football data.

Create an internal endpoint.

// app/api/matches/route.ts

import { NextRequest, NextResponse } from "next/server"
import { getMatchesByDate } from "@/lib/get-matches"

export async function GET(
  request: NextRequest
) {
  const date =
    request.nextUrl.searchParams.get("date")

  if (!date || !isValidDate(date)) {
    return NextResponse.json(
      {
        error:
          "A valid date in YYYY-MM-DD format is required",
      },
      {
        status: 400,
      }
    )
  }

  try {
    const matches = await getMatchesByDate(date)

    return NextResponse.json(
      {
        matches,
        updatedAt: new Date().toISOString(),
      },
      {
        headers: {
          "Cache-Control":
            "public, s-maxage=10, stale-while-revalidate=20",
        },
      }
    )
  } catch (error) {
    console.error(
      "Failed to load football matches",
      error
    )

    return NextResponse.json(
      {
        error:
          "Football data is temporarily unavailable",
      },
      {
        status: 503,
      }
    )
  }
}

function isValidDate(value: string): boolean {
  return /^\d{4}-\d{2}-\d{2}$/.test(value)
}

This endpoint becomes the boundary between the browser and the football provider.

Later, you can add:

Rate limiting
Authentication
Analytics
Provider fallback
Region-specific caching
Subscription checks
Request tracing

Stop Polling When Nothing Is Live

This was the easiest improvement and one of the most valuable.

My original app refreshed the match list every five seconds, even when every match was finished.

A finished score is unlikely to change.

A match scheduled for tomorrow does not need to be requested every few seconds.

The polling logic should depend on the match state.

// components/match-center.tsx

"use client"

import {
  useCallback,
  useEffect,
  useRef,
  useState,
} from "react"

import type { FootballMatch } from "@/types/match"
import { MatchList } from "@/components/match-list"

type MatchCenterProps = {
  date: string
  initialMatches: FootballMatch[]
}

export function MatchCenter({
  date,
  initialMatches,
}: MatchCenterProps) {
  const [matches, setMatches] =
    useState(initialMatches)

  const [lastUpdated, setLastUpdated] =
    useState<string | null>(null)

  const [error, setError] =
    useState<string | null>(null)

  const currentRequest =
    useRef<AbortController | null>(null)

  const hasLiveMatches = matches.some(
    (match) =>
      match.status === "live" ||
      match.status === "halftime"
  )

  const refreshMatches = useCallback(
    async () => {
      currentRequest.current?.abort()

      const controller = new AbortController()
      currentRequest.current = controller

      try {
        const response = await fetch(
          `/api/matches?date=${encodeURIComponent(date)}`,
          {
            cache: "no-store",
            signal: controller.signal,
          }
        )

        if (!response.ok) {
          throw new Error(
            `Request failed with ${response.status}`
          )
        }

        const data = await response.json()

        setMatches(data.matches)
        setLastUpdated(data.updatedAt)
        setError(null)
      } catch (error) {
        if (
          error instanceof DOMException &&
          error.name === "AbortError"
        ) {
          return
        }

        console.error(error)

        setError(
          "Live updates are temporarily delayed."
        )
      }
    },
    [date]
  )

  useEffect(() => {
    if (!hasLiveMatches) {
      return
    }

    const intervalId = window.setInterval(
      refreshMatches,
      15_000
    )

    return () => {
      window.clearInterval(intervalId)
      currentRequest.current?.abort()
    }
  }, [hasLiveMatches, refreshMatches])

  return (
    <section>
      {lastUpdated && (
        <small>
          Updated{" "}
          {new Date(
            lastUpdated
          ).toLocaleTimeString()}
        </small>
      )}

      {error && (
        <p role="status">{error}</p>
      )}

      <MatchList matches={matches} />
    </section>
  )
}

The important check is:

if (!hasLiveMatches) {
  return
}

When no match is live, the refresh interval is not created.

Old Requests Can Overwrite New Scores

Polling introduces a race condition that is easy to miss.

Imagine these two requests:

Request A starts at 14:30:00
Request B starts at 14:30:15

Request B returns first with a score of 2-1
Request A returns later with a score of 1-1

If both responses update the same state, the app shows the older score after the newer one.

From the user's perspective, the score moves backward.

This does not necessarily mean the football API returned incorrect data.

It may mean the responses arrived in the wrong order.

That is why the component aborts the previous request before starting a new one.

currentRequest.current?.abort()

const controller = new AbortController()
currentRequest.current = controller

The older request is no longer allowed to overwrite the newest result.

Do Not Delete Good Data Because One Refresh Failed

My first error handler replaced the match list with an empty array.

That was a bad decision.

A score that is fifteen seconds old is usually more useful than no score at all.

When a background refresh fails, keep the last successful data visible.

try {
  const latestMatches = await loadMatches()

  setMatches(latestMatches)
  setError(null)
} catch {
  setError(
    "Updates are delayed. Showing the latest available scores."
  )
}

The UI should communicate that the data may be stale, but it should not destroy useful information.

A live football app has more states than just loading, success, and error.

Initial loading
Fresh data
Refreshing
Temporarily stale data
Partial data
Provider unavailable
Recovered

Designing for these states makes the app feel much more stable.

Match Status Should Control Behavior

At first, I treated match status as a label.

<span>{match.status}</span>

But status is not only presentation data.

It should control the application.

For example:

// lib/match-status.ts

import type { FootballMatch } from "@/types/match"

export function isLive(
  match: FootballMatch
): boolean {
  return (
    match.status === "live" ||
    match.status === "halftime"
  )
}

export function isFinished(
  match: FootballMatch
): boolean {
  return match.status === "finished"
}

export function canStillChange(
  match: FootballMatch
): boolean {
  return (
    match.status === "scheduled" ||
    match.status === "live" ||
    match.status === "halftime"
  )
}

These helpers can determine:

Whether polling should continue
Whether the minute should be shown
Whether kickoff time should be displayed
Whether the score is final
Whether notifications can still be triggered
Whether standings may need updating

As the app grows, you may need additional states such as:

Extra time
Penalties
Interrupted
Abandoned
Delayed
Awarded

Normalizing those states early prevents status checks from spreading throughout the codebase.

Group Matches by Competition

A flat list works when there are five matches.

It becomes difficult to read when there are fifty.

Group the matches by league or competition before rendering them.

// lib/group-matches.ts

import type { FootballMatch } from "@/types/match"

type CompetitionGroup = {
  id: string
  name: string
  country: string | null
  matches: FootballMatch[]
}

export function groupMatchesByCompetition(
  matches: FootballMatch[]
): CompetitionGroup[] {
  const groups = new Map<
    string,
    CompetitionGroup
  >()

  for (const match of matches) {
    const competitionId =
      match.competition.id

    const existing =
      groups.get(competitionId)

    if (existing) {
      existing.matches.push(match)
      continue
    }

    groups.set(competitionId, {
      id: competitionId,
      name: match.competition.name,
      country: match.competition.country,
      matches: [match],
    })
  }

  return Array.from(groups.values())
}

Then render each competition separately.

// components/match-list.tsx

import { groupMatchesByCompetition } from "@/lib/group-matches"
import type { FootballMatch } from "@/types/match"
import { MatchRow } from "@/components/match-row"

type MatchListProps = {
  matches: FootballMatch[]
}

export function MatchList({
  matches,
}: MatchListProps) {
  const groups =
    groupMatchesByCompetition(matches)

  if (groups.length === 0) {
    return (
      <p>No matches are available.</p>
    )
  }

  return (
    <div>
      {groups.map((group) => (
        <section key={group.id}>
          <header>
            {group.country && (
              <span>{group.country}</span>
            )}

            <h2>{group.name}</h2>
          </header>

          <div>
            {group.matches.map((match) => (
              <MatchRow
                key={match.id}
                match={match}
              />
            ))}
          </div>
        </section>
      ))}
    </div>
  )
}

The data structure now supports the interface instead of forcing every component to repeat the same transformation.

A Simple Match Row

Once the data is normalized, the UI becomes much easier to write.

// components/match-row.tsx

import type { FootballMatch } from "@/types/match"
import { isLive } from "@/lib/match-status"

type MatchRowProps = {
  match: FootballMatch
}

export function MatchRow({
  match,
}: MatchRowProps) {
  return (
    <article>
      <div>
        <span>{match.homeTeam.name}</span>

        {match.homeTeam.logoUrl && (
          <img
            src={match.homeTeam.logoUrl}
            alt=""
            width={24}
            height={24}
          />
        )}
      </div>

      <div>
        {match.status === "scheduled" ? (
          <time dateTime={match.startsAt}>
            {new Date(
              match.startsAt
            ).toLocaleTimeString([], {
              hour: "2-digit",
              minute: "2-digit",
            })}
          </time>
        ) : (
          <strong>
            {match.score.home ?? 0}
            {" - "}
            {match.score.away ?? 0}
          </strong>
        )}

        {isLive(match) && (
          <span>
            {match.minute
              ? `${match.minute}'`
              : "LIVE"}
          </span>
        )}
      </div>

      <div>
        {match.awayTeam.logoUrl && (
          <img
            src={match.awayTeam.logoUrl}
            alt=""
            width={24}
            height={24}
          />
        )}

        <span>{match.awayTeam.name}</span>
      </div>
    </article>
  )
}

The component does not know anything about the external provider.

It only understands the application's FootballMatch type.

Caching Does Not Mean Showing Old Scores for Minutes

Developers sometimes avoid caching live data because they assume a cache will make the app feel outdated.

That depends on the cache duration.

A short shared cache can reduce duplicate requests without creating a noticeable delay.

For example:

Browser refresh interval:       15 seconds
Server cache duration:          10 seconds
Stale-while-revalidate window:  20 seconds

Users still receive frequent updates.

But if hundreds of users request the same match data within a short period, the server can reuse the result.

Without shared caching:

500 users
500 external API requests

With a short server cache:

500 users
A much smaller number of external API requests

Live does not always mean uncached.

It often means briefly cached and frequently refreshed.

The Final Request Flow

After restructuring the application, one visit follows this flow:

User opens the football app

Server Component
  Fetches today's matches
  Uses a short shared cache
  Maps the provider response
  Renders the initial page

Browser
  Displays matches immediately
  Checks whether any match is live

If a match is live
  Starts a refresh interval
  Requests updates from the internal API route

Route Handler
  Validates the date
  Reuses recent shared data when possible
  Calls the football provider when needed
  Returns normalized match objects

Client Component
  Cancels the previous request
  Applies the newest result
  Keeps old data if refreshing fails
  Stops polling when all matches finish

Every layer now has a clear responsibility.

The Mental Model That Helped Me

The football provider supplies the raw data.

The server protects, caches, validates, and normalizes it.

The browser renders the data and requests updates only while they are useful.

That is the architecture I wish I had used from the beginning.

My first version was not wrong because it used polling.

It was wrong because polling was the entire architecture.

There was no protection against duplicate requests, stale responses, race conditions, provider changes, or finished matches that could no longer change.

What I Would Add Next

Once the live match flow is stable, the same foundation can support:

Match detail pages
Goals, cards, and substitutions
Starting lineups
League standings
Team pages
Player statistics
Favorite teams
Goal notifications
Match search
User time zones
WebSocket updates
Server-Sent Events
Multiple sports

The important part is keeping the same data flow:

External provider
  ↓
Server-side client
  ↓
Mapping layer
  ↓
Application data functions
  ↓
Route Handler or Server Component
  ↓
User interface

When these boundaries remain clear, adding new football features becomes much easier.

Final Lesson

The visible part of a football app is simple.

Two teams.

One score.

One match clock.

The difficult part is making sure every user sees the newest correct version without generating unnecessary requests or exposing private credentials.

A demo only needs to display football data.

A real football product needs to manage:

Live updates
Shared caching
Request ordering
Match states
Provider failures
Stale data
API security
Response normalization
Rendering performance

My app worked perfectly before matchday because it had never experienced matchday conditions.

The busy afternoon did not break the application.

It revealed the application I had actually built.

Have you ever built a live sports app? What was the first problem that only appeared after real users arrived?