Soccer API Documentation for Developers

Implementation notice: The base URL, authentication method, endpoint paths, field names, request quotas, WebSocket protocol and response examples on this page are documentation placeholders until the final production Soccer API specification is supplied. Replace them with confirmed values before publishing.

Documentation overview

Soccer API Documentation Contents

Quick Start

Make your first authenticated Soccer API request.

Authentication

Protect and send your API credential correctly.

Competitions

Retrieve supported leagues, cups, tournaments and seasons.

Fixtures

Load upcoming, live, completed and historical matches.

Live Scores

Retrieve current score, clock, period and match status.

Match Events

Process goals, cards, substitutions, penalties and VAR.

Standings

Access league tables, points, form and goal difference.

Teams

Retrieve team profiles, squads, fixtures and statistics.

Players

Access player identities, positions and performance data.

Line-Ups

Load starters, substitutes, formations and positions.

Statistics

Retrieve match, team and player statistics.

Head-to-Head

Compare previous meetings between two teams.

Odds

Retrieve supported bookmakers, markets and prices.

Predictions

Use supported probabilities and forecast outputs.

Historical Data

Access previous seasons, results, events and statistics.

WebSocket

Subscribe to real-time soccer events where available.

Rate Limits

Manage quotas, caching and retry behaviour.

Errors

Handle validation, authentication and server errors.

Quick start

Make Your First Soccer API Request

A typical integration sends an authenticated HTTPS request to the API and receives a structured JSON response. Keep permanent private API credentials on your backend whenever possible.

Example Base URL

https://api.example.com/v1

Replace the example host with the confirmed production Soccer API base URL.

Example Request

GET https://api.example.com/v1/soccer/matches/live

Authorization: Bearer YOUR_API_KEY
Accept: application/json

Example Response

{
  "data": [
    {
      "match_id": "match_74021",
      "status": "live",
      "period": "second_half",
      "minute": 67,
      "injury_time": 0,
      "competition": {
        "id": "competition_24",
        "name": "Example Premier League"
      },
      "home_team": {
        "id": "team_18",
        "name": "North City",
        "score": 2
      },
      "away_team": {
        "id": "team_29",
        "name": "United Athletic",
        "score": 1
      },
      "updated_at": "2026-08-06T10:31:22Z"
    }
  ]
}

Recommended Integration Flow

Store your API credential securely
Request supported competitions
Retrieve fixtures for the required date or competition
Store stable match, team and competition identifiers
Load complete match state through REST
Subscribe to WebSocket events where supported
Cache responses and handle rate limits
Reconcile final match data after full time

Authentication

Authenticate Soccer API Requests

Every protected request must include a valid API credential using the authentication format confirmed by the production specification.

Illustrative Bearer Authentication

Authorization: Bearer YOUR_API_KEY

Credential Security

Store production credentials in server environment variables
Do not paste private keys into WordPress page content
Do not expose permanent keys in public browser JavaScript
Do not commit credentials to public source repositories
Rotate any key that may have been exposed
Use IP, domain or application restrictions when supported

Authentication Errors

Status	Meaning	Recommended action
401	Missing, invalid or expired credential	Verify the key and authentication format
403	Credential does not have access to the resource	Check plan, permissions and competition coverage

Competitions and seasons

Retrieve Supported Soccer Competitions

Illustrative Endpoint

GET /v1/soccer/competitions

Example Query Parameters

Parameter	Example	Purpose
country	example-country	Filter by country or territory
type	league	Filter leagues, cups or tournaments
season	2026	Return competitions available in a season
live	true	Filter competitions with live coverage

Example Response

{
  "data": [
    {
      "competition_id": "competition_24",
      "name": "Example Premier League",
      "type": "league",
      "country": {
        "code": "EX",
        "name": "Example Country"
      },
      "current_season": "2026",
      "coverage": {
        "fixtures": true,
        "live_scores": true,
        "events": true,
        "lineups": true,
        "statistics": true,
        "odds": "plan_dependent",
        "predictions": "plan_dependent"
      }
    }
  ]
}

View Soccer API Coverage

Fixtures and results

Retrieve Soccer Fixtures

Illustrative Endpoint

GET /v1/soccer/matches

Example Query Parameters

Parameter	Example	Purpose
competition_id	competition_24	Filter by competition
season	2026	Filter by season
date	2026-08-06	Return matches on one date
date_from	2026-08-01	Start of a date range
date_to	2026-08-31	End of a date range
status	scheduled	Filter by match status
team_id	team_18	Return matches involving one team
page	1	Pagination page

Example Request

GET /v1/soccer/matches
    ?competition_id=competition_24
    &season=2026
    &status=scheduled

Common Match Status Values

scheduled
delayed
first_half
halftime
second_half
extra_time
penalty_shootout
completed
postponed
abandoned
cancelled

Live scores

Retrieve Live Soccer Scores

All Live Matches

GET /v1/soccer/matches/live

One Match

GET /v1/soccer/matches/{match_id}

Example Match Response

{
  "data": {
    "match_id": "match_74021",
    "status": "live",
    "period": "second_half",
    "minute": 67,
    "injury_time": 0,
    "score": {
      "home": 2,
      "away": 1,
      "halftime_home": 1,
      "halftime_away": 1
    },
    "home_team": {
      "id": "team_18",
      "name": "North City"
    },
    "away_team": {
      "id": "team_29",
      "name": "United Athletic"
    },
    "updated_at": "2026-08-06T10:31:22Z"
  }
}

Integration Guidance

Use the match identifier as the stable primary reference
Preserve the official match status
Show the last-updated time in live interfaces
Handle injury time and match periods explicitly
Stop frequent polling after a match is completed
Use a shared server-side cache for multiple users

Explore Live Soccer Scores API

Match events

Retrieve Soccer Match Events

Illustrative Endpoint

GET /v1/soccer/matches/{match_id}/events

Example Event Response

{
  "data": [
    {
      "event_id": "event_991827",
      "match_id": "match_74021",
      "type": "goal",
      "sequence": 184,
      "period": "second_half",
      "minute": 67,
      "injury_time": 0,
      "team_id": "team_18",
      "player_id": "player_301",
      "assist_player_id": "player_447",
      "goal_type": "open_play",
      "status": "confirmed",
      "score_after_event": {
        "home": 2,
        "away": 1
      },
      "created_at": "2026-08-06T10:31:22Z"
    }
  ]
}

Common Event Types

goal
own_goal
goal_disallowed
yellow_card
second_yellow_card
red_card
substitution
penalty_awarded
penalty_scored
penalty_missed
var_decision
match_status

Prevent Duplicate Processing

Store every unique event identifier
Track sequence numbers where available
Apply each event only once
Handle corrections and reversals explicitly
Reconcile local state after a connection interruption

Standings

Retrieve Soccer League Standings

Illustrative Endpoint

GET /v1/soccer/competitions/{competition_id}/standings

Example Request

GET /v1/soccer/competitions/competition_24/standings
    ?season=2026

Example Response

{
  "data": {
    "competition_id": "competition_24",
    "season": "2026",
    "standings": [
      {
        "position": 1,
        "team_id": "team_18",
        "team_name": "North City",
        "played": 28,
        "won": 19,
        "drawn": 5,
        "lost": 4,
        "goals_for": 61,
        "goals_against": 29,
        "goal_difference": 32,
        "points": 62,
        "form": ["W", "W", "D", "W", "L"]
      }
    ],
    "updated_at": "2026-08-06T10:30:00Z"
  }
}

Possible Standing Types

Overall table
Home table
Away table
Group-stage table
Form table

Teams

Retrieve Soccer Team Data

List Teams

GET /v1/soccer/teams

One Team

GET /v1/soccer/teams/{team_id}

Team Fixtures

GET /v1/soccer/teams/{team_id}/matches

Team Statistics

GET /v1/soccer/teams/{team_id}/statistics

Example Team Response

{
  "data": {
    "team_id": "team_18",
    "name": "North City",
    "country": "Example Country",
    "founded": 1908,
    "venue": {
      "id": "venue_81",
      "name": "Central Stadium"
    },
    "current_competitions": [
      {
        "id": "competition_24",
        "name": "Example Premier League"
      }
    ]
  }
}

Team logos, badges and trademarks may require separate display rights.

Players

Retrieve Soccer Player Data

Search Players

GET /v1/soccer/players

One Player

GET /v1/soccer/players/{player_id}

Player Statistics

GET /v1/soccer/players/{player_id}/statistics

Example Query

GET /v1/soccer/players/player_301/statistics
    ?competition_id=competition_24
    &season=2026

Example Player Response

{
  "data": {
    "player_id": "player_301",
    "name": "A. Morgan",
    "position": "Forward",
    "team_id": "team_18",
    "season": "2026",
    "appearances": 28,
    "starts": 25,
    "minutes": 2241,
    "goals": 17,
    "assists": 9,
    "yellow_cards": 3,
    "red_cards": 0
  }
}

Line-ups and formations

Retrieve Soccer Line-Ups

Illustrative Endpoint

GET /v1/soccer/matches/{match_id}/lineups

Example Response

{
  "data": {
    "match_id": "match_74021",
    "status": "confirmed",
    "home_team": {
      "team_id": "team_18",
      "formation": "4-3-3",
      "starting_players": [
        {
          "player_id": "player_301",
          "name": "A. Morgan",
          "position": "Forward",
          "shirt_number": 9
        }
      ],
      "substitutes": []
    },
    "away_team": {
      "team_id": "team_29",
      "formation": "4-2-3-1",
      "starting_players": [],
      "substitutes": []
    },
    "updated_at": "2026-08-06T16:45:00Z"
  }
}

Line-Up Guidance

Distinguish expected from confirmed line-ups
Show the publication timestamp
Preserve stable player and team IDs
Handle late changes before kickoff
Do not present squad membership as confirmed selection

Statistics

Retrieve Soccer Match, Team and Player Statistics

Match Statistics

GET /v1/soccer/matches/{match_id}/statistics

Team Statistics

GET /v1/soccer/teams/{team_id}/statistics

Player Statistics

GET /v1/soccer/players/{player_id}/statistics

Example Match Statistics Response

{
  "data": {
    "match_id": "match_74021",
    "home_team": {
      "team_id": "team_18",
      "possession": 62.0,
      "shots": 14,
      "shots_on_target": 6,
      "corners": 7,
      "fouls": 10,
      "yellow_cards": 2,
      "red_cards": 0,
      "passes": 534,
      "pass_accuracy": 87.2
    },
    "away_team": {
      "team_id": "team_29",
      "possession": 38.0,
      "shots": 8,
      "shots_on_target": 3,
      "corners": 2,
      "fouls": 13,
      "yellow_cards": 3,
      "red_cards": 0,
      "passes": 321,
      "pass_accuracy": 79.4
    }
  }
}

Statistics Best Practices

Show competition, season and sample-size context
Distinguish unavailable values from genuine zero values
Use stable player and team identifiers
Cache historical statistics appropriately
Use documented definitions for advanced metrics

Explore Soccer Statistics API

Head-to-head

Retrieve Previous Meetings Between Two Teams

Illustrative Endpoint

GET /v1/soccer/head-to-head

Example Request

GET /v1/soccer/head-to-head
    ?team_a_id=team_18
    &team_b_id=team_29
    &limit=10

Example Response

{
  "data": {
    "team_a_id": "team_18",
    "team_b_id": "team_29",
    "summary": {
      "matches": 10,
      "team_a_wins": 5,
      "draws": 2,
      "team_b_wins": 3,
      "team_a_goals": 18,
      "team_b_goals": 13,
      "both_teams_scored": 6,
      "over_2_5_goals": 7
    },
    "meetings": []
  }
}

Explore Soccer Head-to-Head API

Odds

Retrieve Soccer Betting Markets and Prices

Odds endpoints may be restricted by plan, competition, bookmaker, market and jurisdiction.

Illustrative Endpoint

GET /v1/soccer/matches/{match_id}/odds

Example Response

{
  "data": {
    "match_id": "match_74021",
    "updated_at": "2026-08-06T10:30:18Z",
    "bookmakers": [
      {
        "bookmaker_id": "bookmaker_12",
        "name": "Example Sportsbook",
        "markets": [
          {
            "market_id": "market_match_winner",
            "status": "open",
            "is_live": true,
            "outcomes": [
              {
                "selection_id": "home",
                "name": "North City",
                "price": 1.84,
                "price_format": "decimal"
              },
              {
                "selection_id": "draw",
                "name": "Draw",
                "price": 3.45,
                "price_format": "decimal"
              },
              {
                "selection_id": "away",
                "name": "United Athletic",
                "price": 4.20,
                "price_format": "decimal"
              }
            ]
          }
        ]
      }
    ]
  }
}

Odds Handling

Display bookmaker attribution where required
Preserve market and selection identifiers
Show update timestamps
Do not present suspended prices as active
Confirm storage and commercial-use rights

Explore Soccer Odds API

Predictions

Retrieve Soccer Predictions and Probabilities

Illustrative Endpoint

GET /v1/soccer/matches/{match_id}/prediction

Example Prediction Response

{
  "data": {
    "match_id": "match_74021",
    "prediction_type": "pre_match",
    "generated_at": "2026-08-06T12:00:00Z",
    "model_version": "soccer_result_v3",
    "probabilities": {
      "home_win": 0.48,
      "draw": 0.27,
      "away_win": 0.25
    },
    "expected_goals": {
      "home": 1.58,
      "away": 1.09
    },
    "markets": {
      "both_teams_to_score_yes": 0.54,
      "over_2_5_goals": 0.51
    },
    "confidence": "moderate"
  }
}

Predictions are probability-based estimates, not guaranteed outcomes. Display generation time, confidence and limitations clearly.

Explore Soccer Predictions API

Historical data

Retrieve Historical Soccer Data

Historical depth can vary by competition, season and data category. Confirm the earliest supported season for every endpoint required by your product.

Possible Historical Resources

Fixtures and results
Standings
Match events
Line-ups and formations
Match statistics
Player season statistics
Head-to-head meetings
Historical odds snapshots
Historical predictions where preserved

Example Historical Query

GET /v1/soccer/matches
    ?competition_id=competition_24
    &season=2022
    &status=completed

Historical Data Guidance

Record competition and season context
Check for missing seasons or fields
Preserve stable entity identifiers
Confirm storage and machine-learning rights
Handle corrections and revised results

WebSocket

Subscribe to Real-Time Soccer Events

WebSocket access may be available for supported plans and competitions. Use REST to load the complete match state before subscribing.

Illustrative WebSocket URL

wss://stream.example.com/v1/soccer

Illustrative Authentication Message

{
  "action": "authenticate",
  "token": "SHORT_LIVED_ACCESS_TOKEN"
}

Subscribe to Match Events

{
  "action": "subscribe",
  "channel": "match_events",
  "match_ids": [
    "match_74021"
  ]
}

Example Live Event

{
  "event_id": "event_991827",
  "match_id": "match_74021",
  "type": "goal",
  "sequence": 184,
  "minute": 67,
  "team_id": "team_18",
  "player_id": "player_301",
  "score": {
    "home": 2,
    "away": 1
  },
  "created_at": "2026-08-06T10:31:22Z"
}

Recommended WebSocket Workflow

Load the current match state through REST
Open the authenticated WebSocket connection
Subscribe to the required matches
Apply each unique event once
Respond to heartbeat messages
Reconnect with controlled backoff after interruption
Request the latest REST state again
Reconcile and continue streaming

Explore Soccer WebSocket API

Pagination

Paginate Large Soccer Data Responses

List endpoints may return data in pages. Follow the confirmed pagination fields in the production specification.

Example Request

GET /v1/soccer/matches?page=2&page_size=100

Example Pagination Object

{
  "pagination": {
    "page": 2,
    "page_size": 100,
    "total_items": 438,
    "total_pages": 5,
    "has_next_page": true
  }
}

Rate limits

Manage Soccer API Rate Limits

Final quotas and response headers depend on the selected plan. Do not publish numeric limits until they are confirmed.

Possible Rate-Limit Headers

X-RateLimit-Limit: PLAN_LIMIT
X-RateLimit-Remaining: REMAINING_REQUESTS
X-RateLimit-Reset: RESET_TIMESTAMP
Retry-After: RETRY_SECONDS

Rate-Limit Best Practices

Cache fixtures and historical data on your server
Share one live response across multiple users
Stop polling completed matches
Use WebSocket delivery where appropriate
Respect Retry-After guidance
Monitor usage before major competitions

Errors

Handle Soccer API Errors

Example Error Response

{
  "error": {
    "code": "invalid_parameter",
    "message": "The supplied match identifier is invalid.",
    "request_id": "request_781922"
  }
}

Status	Meaning	Recommended action
400	Invalid request or parameter	Validate the request before retrying
401	Authentication failed	Verify the API credential
403	Resource not available to the plan	Check permissions and coverage
404	Resource not found	Verify the identifier
409	Request conflicts with current state	Refresh the resource before retrying
422	Validation failed	Review field-level error details
429	Rate limit exceeded	Wait and follow retry guidance
500	Temporary server error	Retry with controlled backoff
503	Service temporarily unavailable	Use cached state and retry later

Code examples

Soccer API Request Examples

These examples are illustrative. Use the confirmed production host and authentication format.

JavaScript

const response = await fetch(
  'https://api.example.com/v1/soccer/matches/live',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  }
);

if (!response.ok) {
  throw new Error(`API error: ${response.status}`);
}

const data = await response.json();

Python

import requests

response = requests.get(
    "https://api.example.com/v1/soccer/matches/live",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/json",
    },
    timeout=15,
)

response.raise_for_status()
data = response.json()

PHP

<?php

$url = 'https://api.example.com/v1/soccer/matches/live';

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_API_KEY',
        'Accept: application/json',
    ],
    CURLOPT_TIMEOUT => 15,
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

curl_close($ch);

Versioning

API Versioning and Changes

Production documentation should explain how breaking and non-breaking changes are released.

Versioned Base Path

Use a path such as /v1/ to separate major API versions.

Changelog

Publish new fields, endpoint changes, deprecations and fixes.

Deprecation Notice

Give developers time to migrate before removing a supported field or endpoint.

Stable Identifiers

Avoid changing match, team, player and competition IDs without a documented migration.

Production guidance

Soccer API Integration Best Practices

Protect Credentials

Route requests through your backend and keep private credentials outside public code.

Use Stable IDs

Store match, team, player, competition, bookmaker and event identifiers.

Cache by Data Type

Cache historical data longer than live match state.

Handle Status Correctly

Respect scheduled, delayed, live, interrupted and completed states.

Prevent Duplicates

Process each event once and reconcile after connection failures.

Monitor Freshness

Display update times and avoid showing stale information as live.

Handle Missing Data

Distinguish unavailable values from genuine zero values.

Respect Licensing

Confirm display, storage, redistribution and commercial-use rights.

Frequently asked questions

Soccer API Documentation FAQs

Where do I get an API key?

Obtain the credential through the final account dashboard, subscription process or support channel.

Can I use the API directly in browser JavaScript?

Only when the provider explicitly supports safe public-client access. Private credentials should remain on your backend.

Does every competition include every endpoint?

No. Fixtures, live scores, events, line-ups, statistics, odds, predictions and history can have different coverage.

Should I use REST or WebSocket?

Use REST for complete state and WebSocket for incremental live updates where supported.

How do I handle duplicate events?

Store unique event identifiers and apply each event only once.

How should injury time be displayed?

Use the documented period, minute and injury-time fields rather than calculating official time from a local stopwatch.

How do I recover after a WebSocket disconnect?

Reload the authoritative REST state, reconnect, authenticate and resubscribe.

How do I confirm final endpoint details?

Replace every placeholder on this page with the approved production specification before publishing.

Start building

Integrate Soccer Data Into Your Product

Confirm your required competitions, endpoints, request volume and commercial use before selecting a production plan.

View API Pricing → Check API Coverage