Skip to content
Tutorials/Getting startedBeginner9 min read

Make your first FootballAPI.net request

Create an account, activate the right football plan, keep your API key server-side and make a first authenticated scores request with cURL or PHP.

Flow / Your first successful integration
  1. Step 1: Account

    Choose a plan and activate access

  2. Step 2: Private key

    Create a customer API key

  3. Step 3: Server request

    Send the key in a header

  4. Step 4: Your website

    Render your saved response

Start with an account and an activated plan

Create your FootballAPI.net account and review pricing before collecting data. Registration alone does not activate a feed or start a trial. Starter offers a seven-day trial after completed checkout with a card; it covers five selected leagues and caps successful requests at 5,000 per UTC day. Save your Starter league selection in Dashboard → Settings before making requests. Growth and Pro include all available package leagues.

Create a customer REST key in Dashboard → API keys and save it in your server's secret manager as FOOTBALLAPI_KEY. This guide uses scores because it is in Starter's league-scoped service set as well as Growth and Pro. The global competition directory, standalone profiles and image lookups require Growth or Pro. Widget installation keys cannot replace REST keys.

Try your first scores request from your server

Set FOOTBALLAPI_KEY on your server, then run this Bash command. It uses no query parameters and Starter receives only its saved leagues. A successful empty collection can simply mean no relevant fixtures are present in this snapshot; it is not an authentication failure.

Send credentials through Authorization: Bearer or X-API-Key. Never put a key into a query string, browser script, public repository or image URL. The 60-second timeout leaves room for bounded recovery on a cold source read; it is not a promised response time. Your visitors should read your own saved response rather than waiting on a fresh external request.

bash
curl --fail-with-body --max-time 60 \
  'https://footballapi.net/api/v1/football/scores' \
  -H "Authorization: Bearer ${FOOTBALLAPI_KEY:?Set FOOTBALLAPI_KEY on your server}" \
  -H 'Accept: application/json'

Make the same request in PHP

This server-side PHP example requires PHP 7.3 or newer and the cURL extension. Save it as scores.php and run php scores.php with FOOTBALLAPI_KEY available to that process. It checks the transport status and JSON before exposing football records to the rest of your application.

This snippet fetches and parses a response; it does not yet create a complete public scoreboard. In a production page, render only the fields you need and escape output using your template framework. Handle exceptions with a controlled error response, not a raw stack trace or a log of authentication headers.

php
<?php
$key = getenv('FOOTBALLAPI_KEY');
if (!$key) { throw new RuntimeException('Set FOOTBALLAPI_KEY'); }
$ch = curl_init('https://footballapi.net/api/v1/football/scores');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 60,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key, 'Accept: application/json'],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($body === false || $status !== 200) {
  throw new RuntimeException('Football request failed: HTTP ' . $status);
}
$payload = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
$data = $payload['data'];
$meta = $payload['meta'];
echo json_encode(['data' => $data, 'meta' => $meta], JSON_PRETTY_PRINT);

Inspect the envelope before building the page

The normal successful response separates data from meta. The scores feed contains competition categories inside data.scores; it is not a flat data.matches array. Some field names use an @ prefix. Repeated collections can be a single object or an array, so normalise the correct collection boundary before rendering.

Starter users can take selected league IDs from Dashboard → Settings and match/team IDs from permitted fixtures or squads. Growth and Pro users can also use the global competition directory. Follow the specific endpoint guide next; each one explains its plan access, parameters and required environment variables.

Turn the experiment into a safe application

Add a server timeout, a shared cache and a small request budget before you allow public traffic. A successful API request can count toward usage even when our server reuses its own cached response. Reusing your saved result is what prevents your application from making another customer API request.

Rotate a key immediately if it has been exposed and update the secret on every server that uses it. Do not try to solve a 401 response by repeatedly retrying the same invalid credential.

  • Verify access in the signed-in playground.
  • Discover IDs from actual directory and fixture records.
  • Keep a fetched timestamp next to cached data.
  • Handle empty, missing and failed responses separately.
All 51 tutorials