LogoLogo
Quick StartFootball APIContactAPI 3.0
  • Welcome
  • Changelog
  • Getting Started
    • Get Started
    • Documentation for the documentation
  • Endpoint overview
    • Continents
      • GET All Continents
      • GET Continent by ID
    • Countries
      • GET All Countries
      • GET Country by ID
    • Leagues
      • GET All Leagues
      • GET League by ID
      • GET Leagues by Country ID
      • Search Leagues by Name
    • Seasons
      • GET All Seasons
      • GET Season by ID
    • Fixtures
      • GET Fixture by ID
      • GET Last Updated Fixtures
      • GET Fixtures by Date
      • GET Fixtures by Date Range
      • GET Fixtures by Date Range for Team
      • GET Fixtures by Multiple ID's
      • GET Deleted Fixtures
    • Statistics
    • Livescores
      • GET All Livescores
      • GET All In play Livescores
    • News API
      • GET All News
      • GET News For Upcoming Fixtures
      • GET News by Season ID
    • Commentaries
      • Commentaries by Fixture ID
    • Video Highlights
      • Get Video Highlights by Fixture ID
    • Head 2 Head
      • GET Head 2 Head by Team IDs
    • Standings
      • GET Standings by Season ID
      • GET LIVE Standings
      • GET Standings by Season ID and Round ID
      • GET Standings by Season and Date(time)
      • GET Standings Corrections by Season ID
    • Teams
      • GET Team by ID
      • GET Teams by Country ID
      • GET Teams by Season ID
      • Search Team by Name
      • GET Current Leagues by Team ID
      • Get All Leagues by Team ID
    • Players
      • GET Player by ID
      • GET Players by Country ID
      • Search Player by Name
    • Topscorers
      • GET Topscorers by Season ID
      • GET Topscorers Aggregated by Season ID
    • Rivals
      • GET Rivals by Team ID
    • Venues
      • GET Venue by ID
      • GET Venues by Season ID
    • Rounds
      • GET Rounds by Season ID
      • GET Round by ID
    • Odds
      • GET Odds by Fixture ID and Bookmaker ID
      • GET Odds by Fixture ID and Market ID
      • GET Odds by Fixture ID
      • GET Inplay Odds by Fixture ID
    • Coaches
      • GET Coach by ID
    • Stages
      • GET Stage by ID
      • GET Stages by Season ID
    • Bookmakers
      • GET All Bookmakers by Fixture ID
      • GET All Bookmakers
      • GET Bookmaker by ID
    • Markets
      • GET All Fixtures by Market ID
      • GET All Markets
      • GET Market by ID
    • Team Squads
      • GET Team Squad by Team and Season ID
    • TV Stations
      • GET TV Station by Fixture ID
    • Prediction API
      • GET Leagues and Performances
      • GET Probabilities
      • GET Probabilities by Fixture ID
      • GET Value Bets
      • GET Value Bet by Fixture ID
  • Tutorials
    • Introduction to our API
      • Make your first request
      • Set your time zone
      • Pagination
    • Enriching your response
      • Includes
      • Nested includes
    • Filtering, limiting & sorting
      • Filtering
      • Limiting
      • Sorting
    • Schedule, fixtures & livescores
      • Season schedule
      • Fixtures
      • Livescores
    • Statistics
      • Match statistics
      • Team statistics
      • Player statistics
      • Season statistics
    • League & topscorers standings
      • League standings
      • Topscorers standings
    • Odds & predictions
      • Odds
        • Odds by fixture, bookmaker and market id
        • FlatOdds
        • InplayOdds
      • Predictions
  • MySportmonks
    • How-to build a custom plan
    • ID Finder
  • How-to Guides
    • Get Started with our how-to guides
      • How-to build your API requests
    • Livescores & fixtures
      • How-to build a livescore website
      • How-to build a schedule page
    • Match & team pages
      • How-to build a match page with events and statistics
      • How-to build a match page with line-ups/formations
      • How-to build a team page with season stats and squads
    • How-to build standings and topscorer standings
      • League standings
      • Topscorer standings
    • Odds & predictions
      • How-to build a match page with odds
      • How-to build a betting odds portal
      • How-to use the predictions API
    • How-to build a fantasy game
    • Developer tools
      • How-to use Sportmonks' APIs in Postman
    • How-to keep your database in sync
    • World Cup 2022
    • EURO 2024
    • Football widgets
      • How-to set up football widgets in your web application
      • Configurations
      • Widgets overview
        • Livescore widget
        • International Cup widgets
  • API References
    • API reference guide
    • Data features
    • ID Finder
    • Code libraries
    • Demo response files
    • Statuses and definitions
    • API Rate limiting
    • Response codes
    • Meta description
  • General
  • Sportmonks
  • Plans & pricing
  • FAQ
  • Contact
Powered by GitBook
On this page
  • Step 1: Get the base URL
  • Step 2: Choose and add the endpoint
  • Step 3: Evaluate the response
  • Step 4: Enrichment
  • Step 5: Re-evaluate response
  • Step 6: Go even further beyond

Was this helpful?

Export as PDF
  1. How-to Guides
  2. Get Started with our how-to guides

How-to build your API requests

We'll cover how to build correct API requests with our Football API 2.0

PreviousGet Started with our how-to guidesNextLivescores & fixtures

Last updated 4 years ago

Was this helpful?

In this guide, we’ll be covering how to build API requests with our . The example API request will be focused on getting all the football matches on a certain date by using the . Fixtures is the terminology used for matches.

We’ll be working with a free plan, so we only have access to the Danish Superliga (id: 271) and the Scottish Premiership (id: 501).

Step 1: Get the base URL

The first thing we need to have is our base URL and our API token.

https://soccer.sportmonks.com/api/v2.0/?api_token={API_TOKEN}

Step 2: Choose and add the endpoint

Next, we need to add an endpoint to the base URL. As stated earlier, for this example we want to get all of the fixtures on a certain date. The endpoint for that is called . This will transform our URL into:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/{Date}?api_token={API_TOKEN}

The date has to be in the format of YYYY-MM-DD. In this example, we’ll take the date of 2020-09-26.

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}

Step 3: Evaluate the response

The football API 2.0 will return a ton of information, but the main takeaway is that there are various ids about the fixture, league, season, stage, etc. Other than that, there is also score, time, coaches and standings. Below is a snippet of the output.

{
    "data": [
        {
            "id": 16475331,
            "league_id": 501,
            "season_id": 17141,
            "stage_id": 77447501,
            "round_id": 194976,
            "group_id": null,
            "aggregate_id": null,
            "venue_id": 14509,
            "referee_id": 15815,
            "localteam_id": 338,
            "visitorteam_id": 282,
            "winner_team_id": null,

Step 4: Enrichment

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}

We might be interested in the teams that will be playing against each other. We can then add the following part to our request: &includes=localTeam,visitorTeam. Now our URL will be:

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam

Step 5: Re-evaluate response

Now we have more information about the local and visitor teams. The local team is called Hamilton Academical, with team id 338 and the visitor team is called Dundee United with team id 282.

 "localTeam": {
                "data": {
                    "id": 338,
                    "legacy_id": 693,
                    "name": "Hamilton Academical",
                    "short_code": "HMA",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1874,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/18/338.png",
                    "venue_id": 288196,
                    "current_season_id": 17141
                }
            },
            "visitorTeam": {
                "data": {
                    "id": 282,
                    "legacy_id": 692,
                    "name": "Dundee United",
                    "short_code": "DUD",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1909,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
                    "venue_id": 8947,
                    "current_season_id": 17141
                }

Step 6: Go even further beyond

https://soccer.sportmonks.com/api/v2.0/fixtures/date/2020-09-26?api_token={API_TOKEN}&include=localTeam,visitorTeam.coach
"visitorTeam": {
                "data": {
                    "id": 282,
                    "legacy_id": 692,
                    "name": "Dundee United",
                    "short_code": "DUD",
                    "twitter": null,
                    "country_id": 1161,
                    "national_team": false,
                    "founded": 1909,
                    "logo_path": "https://cdn.sportmonks.com/images//soccer/teams/26/282.png",
                    "venue_id": 8947,
                    "current_season_id": 17141,
                    "coach": {
                        "data": {
                            "coach_id": 896498,
                            "team_id": 201,
                            "country_id": 1161,
                            "common_name": "M. Mellon",
                            "fullname": "Micky Mellon",
                            "firstname": "Micky",
                            "lastname": "Mellon",
                            "nationality": "Scotland",
                            "birthdate": "18/03/1972",
                            "birthcountry": "Scotland",
                            "birthplace": "Paisley",
                            "image_path": "https://cdn.sportmonks.com/images/soccer/players/18/896498.png"
                        }

Now, we can see that the coach of the visitor team is called Micky Mellon with coach id 896498.

See how flexible the API requests and responses can be? You request exactly what you need and the API will return exactly that.

You can check out our if you want more detailed information.

This guide would be pretty short if we were to end here. That’s why we’ll now be our API request with includes. Here is the URL we used previously again.

You can check out our if you want more detailed information.

We can go even further beyond, by using . Let’s say we would like to know more about the coach of the visitor team. We simply add.coachto visitorTeam. The URL then becomes this:

You can check out our if you want more detailed information.

football API 2.0
fixtures by date endpoint
fixtures by date
fixtures & livescores tutorials
enriching
includes tutorial
nested includes
nested includes tutorial