Integration GuidesDocs
v4
Coverage MatrixDocumentationChange LogLog InContact Us
Integration Guides
Coverage MatrixDocumentationChange LogLog InContact Us

Soccer API Basics

Learn important structural concepts of the Soccer API

Intro

Sportradar's Soccer data is delivered as a RESTful B2B (Business-to-Business) API. HTTP requests are made using the API authentication access established in your account.

Data can be returned in either JSON or XML format.


Technical Requirements

To accept data from our API feeds, ensure that your application:

  • Supports TLS 1.2 or above
  • Can follow an HTTP redirect (used in Push and the Images API)

API Style

The Soccer API is a Sportradar General Sport API. This means it was designed specifically for the sport of soccer, and an aim to provide our media customers with in-depth, intuitive, and speedy soccer statistics.

We also provide an additional soccer data API, Soccer Extended.

Our Soccer Extended API provides an expansive array of statistics unavailable in the Soccer API. 100+ unique data points are available, including passes, tackles, dribbles, crosses, blocks, interceptions, chances created, and more!

Over 20 top leagues are available, with 1,000+ total competitions covered. See our Coverage Matrix for a detailed breakdown of competitions and data offered.

Additional features include:

  • XY coordinates for all events
  • Match stats available by period
  • AI-driven live text commentary
  • AI-driven match previews, half summaries, and full time summaries

Real-time customers are also offered two delivery Push Feeds to enhance speed.

An extended Probabilities package is also offered. This add-on includes in-game probability updates and season outrights.


API Coverage

Our API provides coverage across a global suite of men’s and women’s leagues, including top-tier competitions and emerging markets worldwide. Learn more here.

To help developers manage varying levels of data detail, the API is logically organized into 9 tiers—with Tier 1 offering the most comprehensive coverage and Tier 9 the most limited. You can explore which competitions fall under each tier using the Coverage Matrix.

For a specific season, the Season Info endpoint provides valuable metadata about what's included. This includes the availability of:

  • Player Transfers
  • Missing Players
  • Team Squads
  • Season Statistics
  • Match-level coverage granularity, such as extended, deeper, or basic data packages

This tiered structure helps set accurate expectations around data availability and enables more flexible integration across different levels of competition.

⚽

Understanding Competitions and Seasons

  • Competition refers to an organized tournament or league in which teams compete, such as the Premier League, FIFA World Cup, or UEFA Champions League. Each competition has a unique competition_id.
  • Season represents a specific instance or edition of a competition, typically tied to a year or range of years (e.g., Premier League 2024/25). Each season has a unique season_id and includes all matches, teams, and data for that timeframe within the competition.

Data Collection

The Soccer API is available in version v4, which includes our most up-to-date and stable feature set. We recommend all users adopt and build with this version for the best experience. To access Soccer v4, include v4 in the version parameter of your API requests—no additional configuration is needed.


Supported Languages

The Soccer API supports multiple languages to help you deliver localized experiences to global audiences.

You can request data in various supported languages by including the appropriate language code in your API request.

https://api.sportradar.com/soccer/{access_level}/v4/{language_code}/sport_events/{sport_event_id}/timeline.{format}

This ensures that country names, sport event descriptions, fun facts, other text-based fields are returned in your preferred language where available.

List of Supported Languages

  • da (Danish)
  • de (German)
  • el (Greek)
  • en (English)
  • es (Spanish)
  • fi (Finnish)
  • fr (French)
  • id (Indonesian)
  • it (Italian)
  • ja (Japanese)
  • nl (Dutch)
  • pt (Portuguese)
  • ru (Russian)
  • sr (Serbian)
  • sr1 (Serbian Latin)
  • th (Thai)
  • tr (Turkish)
  • zh (Chinese - simplified)
  • zht (Chinese - traditional)

Versioning

The Soccer API is on version 4, featuring our most up-to-date and stable feature set. We recommend all users adopt and build with this version for the best experience. To access Soccer v4, include v4 in the version parameter of your API requests.


Data Flow and Retrieval

The Soccer API organizes its data into logical endpoints, or feeds. For example, to access a team's schedule you will want to retrieve the Competitor Schedules; to access a match, you will want to retrieve a "Sport Event" feed like Sport Event Timelines or Sport Event Summaries.

The Soccer API is separated into 52 distinct feeds, each with a focused purpose to allow for efficient data retrieval. Depending on your specific need, different feeds and pull frequencies are needed. Use our Soccer Endpoints section for feed documentation and an interactive sandbox.

Most feeds will require the inclusion of a unique Id or parameter. Parameters can range from: season, competition, sport event ID, player ID, or competitor ID. To retrieve these unique Ids you may have to iterate through feeds with larger data sets. See our ID Handling section for more info on Sportradar Ids.

Here is a retrieval path for a player profile.

Step 1

First, make a request to the [Seasons](https://developer.sportradar.com/soccer/reference/soccer-seasons) endpoint. See the [Endpoint Descriptions](https://developer.sportradar.com/soccer/reference/soccer-overview#endpoint-descriptions) section for data to be found in each feed. Locate the unique Id of the team who employs this player.

First, make a request to the Seasons endpoint.

See the Endpoint Descriptions section for data to be found in each feed.

Locate the unique ID of the season in which the player competes.

Step 2

Second, make a request to the [Season Players](https://developer.sportradar.com/soccer/reference/soccer-season-players) feed using your found season Id and locate the unique player Id.

Second, make a request to the Season Players feed using your
found season Id and locate the unique player Id.

Step 3

Third, make a request to the [Player Profile](https://developer.sportradar.com/soccer/reference/soccer-player-profile) feed to find player biographical and competitor information

Third, make a request to the Player Profile feed to find
player biographical and competitor information.

All Soccer API feeds will follow this pulling logic. Visit our Integration Scenarios section for specific retrieval scenarios.

You can also reference our Soccer API Map to get a sense of how the entire API is interconnected.


RESTful & Push

Most of our Soccer endpoints are RESTful, but we also include complementary Push feeds available for Realtime customers.

With RESTful feeds, a request must be made whenever a data update is needed. For our Push feeds, one request will open up a streaming connection. Data is then delivered in a continuous stream indefinitely.

Push feeds correlate to the RESTful endpoints, but are not necessarily 1:1 in parity. For example, the Push Events feed follows the same format, and includes nearly all of the same data, as the Sport Event Timeline RESTful endpoint. And Push Statistics correlates to Sport Event Summary.

For increased data speed, and less API requests, many customers use Push. Though it is important to note that Push feeds are not meant to replace the RESTful data, but to enhance it. RESTful feeds should always be used as the backbone of the Soccer API.

See our Push Feeds section for more info.


Monitoring Data Changes

The Soccer API offers the following feeds to help you track changes to data:

  • Sport Events Created – Returns IDs for sport events created in the last 24 hours.
  • Sport Events Removed – Returns IDs for sport events that have been removed due to entry errors. These IDs remain available in the feed for 2 weeks.
  • Sport Events Updated – Returns IDs for sport events that have been updated in the last 24 hours.

When using the Sport Events Updated feed, you can track updates to matches by using the returned sport_event_id. This allows you to cross-reference with other feeds—such as stats, lineups, or play-by-play—to identify what has changed. Common updates include stat revisions or event corrections. Comparing the latest data with your previously stored data helps you pinpoint what was impacted.


Pagination

The Soccer API uses pagination to manage the volume of data returned in a single response. On busy match days, there may be hundreds of events and thousands of statistics provided. Returning all of this at once could lead to performance issues or timeouts.

For details on how pagination works for supported endpoints, refer to our Soccer API endpoint documentation.


Additional Integration Options


OpenAPI Specs

Soccer

Soccer v4 OpenAPI

Soccer v4 Probabilities OpenAPI

Soccer Extended

Soccer Extended v4 OpenAPI

Soccer Extended v4 Probabilities OpenAPI


Postman Workspace

Our entire Media APIs are available on Postman. Click the link above to be taken directly to our Soccer API collection.

Feel free to follow and/or fork any collections to receive updates.


Schema Download

Open the zip file below to access our entire Soccer API XSD schema.

Soccer v4 Schema

⚽

More Questions?

Check our Soccer API FAQ or reach out to our support team at [email protected]






Updated 4 days ago

© Sportradar AG, St. Gallen, Switzerland