API Structure & Navigation

A high-level walk-through of our API architecture: domains, relationships, routing patterns, and tips to help you quickly find the endpoint you need.

Welcome to the API Structure & navigation page. The roadmap to how our API is organised and how to quickly find what you need. This page will help you:

• Understand the high-level architecture and domains (resources) of our API

• See how the parts relate to each other

• Learn how to navigate / discover endpoints

• Follow suggested entry paths for common use cases

You’ll find direction before diving into a detailed reference.

1. High-level architecture & domains

Below is a conceptual view of how our API is structured in terms of domain areas (resources), their relations, and the patterns we follow.

Domain / Category	Purpose / What It Covers	Relationships / Cross Links
Core / “Static / Metadata”	Entities that change infrequently: leagues, seasons, teams, venues, arenas, countries, referees, etc.	Many of the other domains reference these (e.g. fixtures point to teams, seasons, venues)
Fixtures / Matches	Scheduled matches, live matches, events within matches (goals, cards, substitutions)	Links to teams, players, events, statistics
Players / Squads / Rosters	Player profiles, seasonal stats, transfers, squad membership	Linked to teams, fixtures, stats
Statistics / Analytics	Aggregated / per-match / per-player stats, advanced metrics (e.g. xG, period stats)	Cross-reference to fixtures, players, teams
Odds, Predictions & Markets	Betting odds, markets, predictions, forecasts	Associated with fixtures and events
State / Status / Types	Status definitions (e.g. “live”, “halftime”, “finished”), enum types, constants	Used across many endpoints
Schemas / Definitions	Data models, objects / types used in request/response bodies	Underpins all reference pages
Error Codes & Responses	Standard error structure, codes, messages, and their meanings	Reused everywhere
Utilities / Search / Query Tools	Endpoints to search or list entity names, “find by name / search”, or fetch “available data features”	Helps users locate entities by name / filter

2. URL / Versioning / Request patterns

To use the API effectively, it helps to know our conventions and patterns.

• Base URL & versioning All requests begin with a base URL and version prefix, e.g.

https://api.sportmonks.com/v3/football/…

• Resource path & hierarchy We follow RESTful-like paths, often nested or related. Examples:

  • GET /v3/football/leagues — list available leagues

  • GET /v3/football/fixtures/{fixture_id} — details for a specific match

  • GET /v3/football/teams/{team_id}/players — players in a team

• Query parameters & includes To avoid over fetching, many endpoints allow query parameters such as: include=players,statistics, filter[season]=2024, sort=-date, etc. This lets you customize and shape the data you receive.

• Pagination / limits For endpoints that return collections (lists), we use pagination parameters (e.g. page, limit) and metadata in the response (e.g. meta.total, meta.per_page).

• Error / status codes Standard HTTP codes (200, 400, 401, 404, 429, 500, etc.) are used. Always inspect the error schema for structured error responses.

• Rate limiting & quotas Requests are subject to rate limits / quotas per plan or per entity. Exceeding limits returns a 429. (In API 3.0, rate limits are counted per entity rather than per endpoint)

3. How domains interrelate (diagram & flow)

             +---------------------+
             |     League(s)       |
             +---------------------+
                        |
                        v
             +---------------------+
             |     Season(s)       |
             +---------------------+
                        |
                        v
             +---------------------+
             |    Fixture(s)       |
             +---------------------+
                 /        |        \
                v         v         v
  +-------------+    +--------+    +------------------+
  | Teams        |    | Events |    | Odds / Markets  |
  +-------------+    +--------+    +------------------+
        |                 |
        v                 v
  +-------------+     +-------------+
  | Players      |     | Statistics  |
  +-------------+     +-------------+
        |
        v
  +------------------+
  | Player Attributes|
  +------------------+

Sample narrative flow:

• Leagues contain one or more seasons

• Seasons contain matches / fixtures

• A fixture links to two teams, a venue, match events, statistics

• Teams have rosters (players), which have season stats

• Odds / predictions attach to a fixture or event

• Types / states define enums (e.g. fixture statuses) used by many endpoints

4. How to find what you're looking for

Approach #1: Use domain names / keywords If you know the domain (e.g. “players”, “fixtures”, “odds”), go to that section in the sidebar or via the navigation menu. We group endpoints by domain.

Approach #2: Use search & filtering Our docs support search. Type in keywords (e.g. “match events”, “team stats”, “prediction”) and you’ll get matching pages. You can also search for partial matches – e.g. just “event” to find event-related endpoints.

Approach #3: Use “include / filter / search” utility endpoints We provide endpoints that help you locate by name or filter entities (e.g. search teams by name, fetch leagues with available features). This helps when you don’t have an ID in hand.

Approach #4: Entry path / decision tree Here’s a sample path breakdown for common tasks:

• If you want the match details + events + stats

  1. Use GET /fixtures/{id}

  2. Use include=events,statistics

  3. Or call GET /fixtures/{id}/events, GET /fixtures/{id}/statistics separately

• If you want a team’s players

  1. Use GET /teams/{id} (or GET /teams)

  2. Use include=players,statistics

• If you know a team name but not ID

  1. Use search / “name lookup” endpoint

  2. Get the ID, then use it in your requests

5. Example walkthroughs

Here are a few short examples to illustrate navigation via the structure:

Example A: Fetch upcoming matches for League X and include events

1. Go to League endpoints (domain) → list leagues

2. Identify the league ID

3. Use GET /leagues/{id}/fixtures with filter filter[upcoming]=true

4. Use include=events,team,statistics

Example B: Get stats for a specific player in the current season

1. Go to Players domain → find player by ID or name search

2. Use GET /players/{id}/statistics with filter[season]=2025

Example C: Determine if a given league supports certain data features (e.g. lineups, odds)

1. Use the Features / Utilities endpoint (e.g. /leagues/{id}/features)

2. Inspect returned attributes (e.g. supports_lineups: true)

6. FAQs / Notes on API structure

• Is every domain present for every sport? No. For example, odds or predictions may only apply to certain sports or leagues; features vary by league. In API 3.0, core and odds endpoints are now no longer sport-specific, they exist across sports.

• What about API versioning / deprecation? API 2.0 is still active until at least end of 2025, but we recommend migrating to v3.0. Some endpoints from v2 may no longer appear in v3, or have changed signature. Always check the versioned reference.

• Rate limits & quotas With API 3.0, rate limits are counted per “entity” instead of per endpoint. Exceeding limits will return 429. Use caching, conditional requests, and limiting fields to optimize usage.

• Custom / optional includes We encourage using include and filter parameters to fetch only what you need as this reduces payload size, lowers cost, and speeds performance.

• Error handling Always check the error body (in JSON) for structured error codes and messages. We'll maintain a centralized Error Codes / Responses page so you can map codes to actionable fixes.