How to Use a Football API in JavaScript

Make your first football API request

The example below requests matches scheduled for 28 August 2026. OpenFootAPI returns a response envelope containing data and meta. Always check response.ok before treating the body as a successful result because fetch resolves even when the server returns an HTTP error status.

const response = await fetch(
  "https://openfootapi.com/v1/matches?date=2026-08-28",
  { headers: { Accept: "application/json" } }
);

const body = await response.json();

if (!response.ok) {
  throw new Error(body.error?.message ?? "Football API request failed");
}

console.log(body.data);

Render the matches on a page

Each match contains homeTeam, awayTeam, kickoffAt, status and score. Treat score values as nullable because a scheduled fixture does not yet have a result. Format kickoffAt with Intl.DateTimeFormat so the browser displays the visitor's local time.

const list = document.querySelector("#matches");

for (const match of body.data) {
  const item = document.createElement("li");
  const kickoff = new Intl.DateTimeFormat("en-GB", {
    dateStyle: "medium",
    timeStyle: "short"
  }).format(new Date(match.kickoffAt));

  item.textContent =
    `${match.homeTeam.name} vs ${match.awayTeam.name} — ${kickoff}`;
  list.append(item);
}

Add a bearer API key

Authenticated requests use the standard Authorization header. An OpenFoot API key starts with fs_live_. The API returns usage information in meta.access so a client can see the monthly quota, used requests and remaining allowance.

Do not expose a paid secret in public browser code. Anyone can inspect shipped JavaScript and network requests. Keep production keys on a server, serverless function or backend proxy, then let the browser call your own endpoint.

const response = await fetch(
  "https://openfootapi.com/v1/matches?competition=comp_bundesliga_de",
  {
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${process.env.OPENFOOT_API_KEY}`
    }
  }
);

Handle typed errors

A reliable integration should branch on the stable error code rather than comparing complete human-readable messages. OpenFootAPI can return codes such as invalid_api_key, api_key_required, monthly_quota_exceeded and source_unavailable.

if (!response.ok) {
  const { error } = await response.json();

  if (error.code === "monthly_quota_exceeded") {
    // Pause requests or notify the account owner.
  }

  throw new Error(error.message);
}

Can a browser call the API directly?

Yes. OpenFootAPI includes cross-origin response headers and handles browser preflight requests. Public-preview calls can therefore run directly on another website. Authenticated calls also work technically, but a public frontend is not a safe place to store a private API key.

The Fetch API is promise-based and supports cross-origin requests through CORS. A browser only exposes a cross-origin response to JavaScript when the server returns the appropriate access-control headers.