🙋‍♂️Getting Started

We'll briefly inform you about the features of our API, and then you can explore our documentation for yourself. You will also find out how to create your dream application. Sportmonks offers standard REST APIs. Requests are sent with URLs and responses will be returned in JSON format. Every authentication is spearheaded by an API token. We have assembled a library of all of our endpoints including example requests in Postman.

We also offer detailed postman documentation with examples and a complete up-to-date version of all our endpoints. Below is a button that lets your fork the collection or import it

Short introduction to Sportmonks:

Now you know who we are, what we do, what we offer, and how we can help you: We suppose you want to get started right away. Head over to our Getting Started section, where you'll create your own API token and create your first request

What else do we cover in the documentation?

• Getting started

• API section

• Endpoint overview

• Entities explained

• Tutorials

• How-to guides

• Definitions

API structure

Persona-based getting started paths

Different developers have different needs and experience levels. This document provides tailored getting started paths for each user persona, helping them find the most relevant documentation quickly and reducing time-to-first-success.

Choose your path

Select the path that best describes you to get started quickly with the right resources:

New to APIs?

You're here to: Learn what APIs are and how to use Sportmonks for the first time.

Your learning path

Step 1: Understand the basics

• What is an API? - Learn API fundamentals

• What can you do with Sportmonks? - See what's possible

Step 2: Get set up

• Authentication guide - Get your API token

• Making your first request - Send your first API call

Step 3: Learn core concepts (15 min)

• API structure & navigation - How the API is organised

• Fixtures tutorial - Working with match data

• Includes tutorial - Get more data in one request

Step 4: Build something simple (10-15 min)

• Build a simple livescore app- Step-by-step tutorial

• Understanding responses - Read API responses

• Common beginner mistakes - Avoid pitfalls

Experienced developer, new to Sportmonks?

You're here to: Get productive quickly with Sportmonks' most powerful features.

Your fast-track path

Step 1: Quick setup

• Authentication - Get your token

• Quick start guide - Make your first request

• API structure - Understand organisation

Step 2: Power features

• Advanced includes - Combine data efficiently

• Filter & select - Optimise responses

• Rate limiting - Understand limits

Step 3: Essential tutorials

• Livescores & fixtures - Core match data

• Statistics - Advanced stats

• States & types - Reference data

Step 4: Optimise

• Best practices - Production-ready code

• Error handling - Handle errors properly

• Performance tips - Scale efficiently

Pro tips:

• Use ID finder to discover entity IDs

• Test with Postman collection

• Cache reference data (types, states, leagues)

Migrating from API v2?

You're here to: Upgrade from API v2 to v3 smoothly and quickly.

Your migration path

Step 1: Understand changes (10 min)

• Key differences overview - What changed

• API changes - Detailed breakdown

• Syntax changes - New syntax

Step 2: Breaking changes checklist

• Participants replace localTeam/visitorTeam - Update team includes

• New include syntax - Use semicolons (;) instead of commas

• New pagination - No more total_pages in response

• Rate limits per entity - Not per endpoint anymore

• Statistics only show recorded values - No default zeros

• Trends structure changed - New period-based format

• Bookmaker IDs changed - Use legacy_id for mapping

Step 3: New features to explore

• New endpoints - What's new in v3

• Expected goals (xG) - Advanced metrics

• Trends analysis - Form tracking

• Pressure index - Match momentum

Migration checklist:

□ Update base URL to /v3/
□ Replace include commas with semicolons
□ Change localTeam/visitorTeam to participants
□ Update pagination logic (no total_pages)
□ Handle null statistics (not zeros)
□ Test all endpoints in your app
□ Update error handling for new codes
□ Review rate limits per entity

Building specific applications?

Choose your application type for a focused guide:

Livescore app

What you'll build: Real-time match tracker with scores, events, and lineups.

Your path

1. Core features

   • Livescores tutorial - Real-time scores

   • Events tutorial - Goals, cards, subs

   • Lineups tutorial - Team lineups

2. Enhancement features (15 min)

   • Scores by period - Half-time scores

   • States - Match status (NS, LIVE, FT)

   • Fixtures tutorial - Match details

3. Optimisation

   • Polling strategy - How often to refresh

   • Rate limiting - Stay within limits

   • Caching strategy - Improve performance

4. Polish

   • Error Handling - Handle failures

   • Filtering - Show specific leagues

📱 Quick Implementation:

// Fetch live matches with events and lineups
const response = await fetch(
  'https://api.sportmonks.com/v3/football/livescores/inplay?api_token=YOUR_TOKEN&include=scores;events;participants;lineups'
);
const liveMatches = await response.json();

// Poll every 10 seconds for updates
setInterval(async () => {
  const updates = await fetch(
    'https://api.sportmonks.com/v3/football/livescores/latest?api_token=YOUR_TOKEN&include=scores;events'
  );
  // Update your UI with changes
}, 10000);

Betting platform

What you'll build: Platform with odds, predictions, and statistics.

Your path:

1. Foundation

   • Fixtures tutorial - Match data

   • Statistics - Performance data

   • Head-to-head - H2H records

2. Odds & predictions

   • Pre-match odds - Bookmaker odds

   • Live odds - In-play odds

   • Predictions - ML predictions

   • Value bets - Best value

3. Advanced stats

   • Expected goals (xG) - Performance metrics

   • Trends - Form analysis

   • Team statistics - Team performance

4. Implementation

   • Markets & bookmakers - Understanding odds structure

   • Plan requirements - What you need

   • Best practices - Production tips

Fantasy football

What you'll build: Fantasy league with player stats and scoring.

Your path

1. Player data

   • Players - Player profiles

   • Player statistics - Performance metrics

   • Lineups - Starting players

2. Scoring system

   • Statistics types - Available stats

   • Fixture statistics - Match stats

   • Events - Goals, assists, cards

3. League management

   • Fixtures by date - Gameweek fixtures

   • Season schedule - Plan gameweeks

   • Livescores - Live scoring

4. Advanced features

   • Expected goals - xG for players

   • Trends - Form indicators

   • Transfers - Transfer news

Sample fantasy points calculation:

const calculatePoints = (playerStats) => {
  let points = 0;
  
  // Goals: 5 points each
  points += (playerStats.goals || 0) * 5;
  
  // Assists: 3 points each  
  points += (playerStats.assists || 0) * 3;
  
  // Clean sheet (goalkeeper/defender): 4 points
  if (playerStats.cleansheet && ['GK', 'DEF'].includes(playerStats.position)) {
    points += 4;
  }
  
  // Yellow card: -1 point
  points += (playerStats.yellowcards || 0) * -1;
  
  // Red card: -3 points
  points += (playerStats.redcards || 0) * -3;
  
  return points;
};

Stats dashboard

What you'll build: Analytics dashboard with trends, comparisons, and visualizations.

Your path

1. Statistics foundation

   • Statistics tutorial - Overview

   • Season statistics - League stats

   • Team statistics - Team metrics

   • Player statistics - Player metrics

2. Advanced metrics

   • Expected goals (xG) - Performance analysis

   • Trends - Form tracking

   • Pressure index - Match control

3. Comparisons

   • Head-to-head - Team comparisons

   • Standings - League tables

   • Filter & select - Custom queries

4. Visualisation tips

   • Statistics types reference - Understand data

   • Data processing - Clean and format

   • Best practices - Optimise

Dashboard components:

• Team form chart (last 10 matches)

• xG vs actual goals scatter plot

• Player comparison radar charts

• League-wide statistics tables

• Trend lines for key metrics

Additional resources by persona

For beginners

Helpful Guides:

• API glossary - Common terms explained

• Understanding JSON - How to read responses

• Postman tutorial - Test without code

• Common errors - Fix issues

For experienced developers

Advanced topics:

• Nested includes - Complex queries

• Bulk operations - Process multiple entities

Performance:

• Caching strategies - Speed up apps

• Database Design - Store efficiently

• Monitoring - Track usage

For migrators

Migration tools:

• API v2 to v3 Mapping - Endpoint changes

Need help?

Can't find what you're looking for? We're here to help:

Quick help

• Search documentation - Use search bar above

• Browse tutorials - All Tutorials

Direct Support

• Email: [email protected]

• Sales: For plan questions

Report Issues

• Bug report: Submit Issue

• Documentation feedback: Use smile /frown emojis

• Feature request: Submit Request

See also

• Full tutorial index

• API reference

• Best practices

• Error codes