API 4 Sports - Real-Time Sports Data API Provider
Guides

How to Integrate a Sports API (Step-by-Step)

Authenticate requests, fetch data, handle errors, and cache results with real API examples.

2025-10-21· 5 min read

Getting Started with API 4 Sports

Follow these simple steps to start using the API 4 Sports platform and integrate sports data into your application.

Step 1: Create Your Account

Sign up at api4sports.com and choose your subscription package. Packages can include multiple sports (Football, Tennis, etc.) based on your needs.

Step 2: Start Your Free Trial

You get 5 days free without a credit card, or 15 days free with a credit card. Cancel anytime during the trial period with no charges.

Step 3: Get Your API Key

Once registered, you'll receive your unique API key in your dashboard. Keep it secret and never commit it to source control.

Step 4: Make API Calls

Use the endpoints based on your subscription. You can access only the leagues and data included in your plan.

Authentication

All API requests require authentication using an API key. You can send the API key in one of two ways:

  • ✓HTTP Header (Recommended): X-Api-Key: your_api_key_here
  • ✓Query Parameter: ?api_key=your_api_key_here

Your First API Request

Let's fetch all available football leagues. Here's how to do it with cURL:

bash
curl -X GET "https://api.api4sports.com/api/football/leagues?itemsPerPage=15&page=1" \
  -H "X-Api-Key: your_api_key_here"

JavaScript Example

javascript
const response = await fetch('https://api.api4sports.com/api/football/leagues?itemsPerPage=15&page=1', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'your_api_key_here'
  }
});
const data = await response.json();
console.log(data);

Python Example

python
import requests

url = "https://api.api4sports.com/api/football/leagues"
headers = {"X-Api-Key": "your_api_key_here"}
params = {"itemsPerPage": 15, "page": 1}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

Response Example

json
{
  "message": "Success",
  "data": [
    {
      "id": 5961,
      "name": "UEFA Champions League",
      "country": "Europe",
      "year": "2024",
      "country_id": 3,
      "logo": "https://api.api4sports.com/logos/football/logo_leagues/uefa-champions-league.png",
      "importance": 5,
      "date_start": "2024-09-17",
      "date_stop": "2025-05-31"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 15,
    "total": 972,
    "last_page": 65
  }
}

Fetching Matches by Date

Get football matches within a date range. Date range (from/to) is required unless match_id is provided.

bash
curl -X GET "https://api.api4sports.com/api/football/matches?from=2024-01-15&to=2024-01-20&league_id=207" \
  -H "X-Api-Key: your_api_key_here"

JavaScript with Parameters

javascript
const params = new URLSearchParams({
  from: '2024-01-15',
  to: '2024-01-20',
  league_id: '207',
  items_per_page: '50'
});

const response = await fetch(`https://api.api4sports.com/api/football/matches?${params}`, {
  headers: { 'X-Api-Key': 'your_api_key_here' }
});
const data = await response.json();

Match Response Example

json
{
  "success": 1,
  "result": [
    {
      "match_id": 59409,
      "date": "2024-01-15",
      "time": "20:45",
      "country_name": "England",
      "league": "Premier League",
      "league_id": 207,
      "round": 22,
      "result": "2 - 1",
      "live": false,
      "home_team": {
        "id": 96,
        "name": "Manchester United",
        "logo": "https://api.api4sports.com/logos/football/logo_teams/manchester-united.png"
      },
      "away_team": {
        "id": 97,
        "name": "Arsenal"
      },
      "stadium": "Old Trafford",
      "referee": "Michael Oliver"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 200,
    "total": 1500
  }
}

Error Handling

The API uses standard HTTP status codes. Handle these responses appropriately:

  • ✓200 OK — Request successful
  • ✓401 Unauthorized — API key is missing or invalid
  • ✓403 Forbidden — No active plan or no access to this sport/league
  • ✓404 Not Found — Resource not found
  • ✓422 Unprocessable Entity — Validation failed (check parameters)
  • ✓429 Too Many Requests — Daily request limit exceeded

Error Handling in JavaScript

javascript
async function fetchMatches(from, to) {
  try {
    const response = await fetch(
      `https://api.api4sports.com/api/football/matches?from=${from}&to=${to}`,
      { headers: { 'X-Api-Key': process.env.API_KEY } }
    );
    
    if (!response.ok) {
      if (response.status === 401) throw new Error('Invalid API key');
      if (response.status === 403) throw new Error('No access to this league');
      if (response.status === 429) throw new Error('Rate limit exceeded');
      throw new Error(`HTTP error: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

Environment Setup

Store the API key in environment variables and inject it via your deployment platform. Never hardcode secrets.

  • ✓Local: Use .env file + dotenv package
  • ✓Cloud: Use platform secrets (Vercel, Netlify, Railway)
  • ✓Rotate keys periodically and on suspected leaks

Node.js Environment Example

javascript
// .env file
// API_KEY=your_api_key_here

import 'dotenv/config';

const API_KEY = process.env.API_KEY;

const response = await fetch('https://api.api4sports.com/api/football/leagues', {
  headers: { 'X-Api-Key': API_KEY }
});

Available Endpoints

Here are the main endpoints available in the Football API:

  • ✓/football/leagues — Get all active leagues with pagination
  • ✓/football/countries — Get all countries with football leagues
  • ✓/football/countries/{countryId}/leagues — Get leagues by country
  • ✓/football/leagues/{leagueId}/teams — Get teams in a league
  • ✓/football/teams/{teamId}/players — Get players by team
  • ✓/football/matches — Get matches by date range (max 200/page)
  • ✓/football/live — Get live matches with events, lineups, statistics
  • ✓/football/live-odds — Get live odds for ongoing matches
  • ✓/football/pre-match-odds — Get pre-match odds (max 5 days range)
  • ✓/football/matches/{matchId}/details — Full match details
  • ✓/football/leagues/{leagueId}/standings — League standings
  • ✓/football/leagues/{leagueId}/top-scorers — Top scorers by league
  • ✓/players/{playerId}/statistics — Player statistics by season

Next Steps

Now that you've made your first requests, explore more endpoints like live matches, odds, and standings. Check out our other tutorials for building live scoreboards and odds applications.

Back to all articles