# API Structure & Navigation
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.
```bash
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](https://www.sportmonks.com/football-api-3-0-docs/), rate limits are counted per entity rather than per endpoint)
### 3. How domains interrelate (diagram & flow)
**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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/api-structure-and-navigation.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.