It's time to make your first API request. Maybe you've missed it, but we've explained how our API works on our Getting Started page. For your convenience, we've copied the content on this page as well. Already followed all these steps? Then let's get started by setting your own time zone.
To make our first request, we’ll need a way to get authenticated first. Football API 2.0 utilizes API tokens for the authentication of requests. You can obtain your free API token and manage your API tokens Mysportmonks. For the sake of simplicity, we’ll be working with an API token from the free plan. The free plan only has the Danish Superliga (league id: 271) and the Scottish Premiership (league id: 501) included.
Example API token: [HdoiD312ND….]
The API token is only meant for your eyes and, as such, should be stored away safely.
Our tokens have no expiration date and will remain valid until you manually delete them yourself. Football API 2.0 utilizes response codes to indicate successful and failed API requests. When making a request, a code response will always be returned. See below for a shortlist of possible code responses:
With our token in hand, we can finally make the first request!
Now that all prerequisites have been fulfilled, we’re ready to send our first request to the API!
The request consists of the following components:
The base URL
A path parameter, in this example, we use [leagues]
A query string parameter, this is optional, so we leave this out for now
And finally, your API token
An example of a correctly authenticated request would be:
This request will return all of the leagues eligible for our free plan, which are the Danish Superliga (league id: 271) and the Scottish Premiership (league id: 501). You can view them by clicking on the second tab.
The above example was the most basic of basic requests and our advanced and highly flexible football API 2.0 can handle much more than that.
With the data that our API provides you, you too will be able to create excellent applications. Below are two examples of SportMonks’ partners who have made brilliant applications. Throughout all our documentation pages you will find more examples, ranging from betting and odds websites to fantasy games and live score tracking websites.
There are various options as to how you’d like to send the request. Our API is compatible with an incredible number of developer languages
In the previous tutorial, we discussed how you can set your desired timezone. Before we dive into the extra details of our API, we need to discuss one of the fundamentals of our API: pagination.
“How is it possible that I cannot find all the data I requested?”
Responses sometimes return more than 1.000 results. With that much data, requests can become slow and hard to work with. That’s why these endpoints use something called pagination. Instead of returning all 1.000+ results, you'll get a hundred results per page.
Note that every page called counts against the ratelimiter. So a call to page 1,2,3,4 and 5 counts as 5 call against the ratelimiter.
Let's request all the fixtures between two dates. We can do this by using our get fixtures by date range endpoint. In the meta description of the response, you will see information about your subscription, the number of API calls and more. Please refer to our meta description page for more info.
Also, you can see information about the results of the response. In the second tab, you can see that the response returned 13454 results, but the API only shows a hundred results per page. With pagination, it results in 135 pages.
"So, how do I get to the second page then?’"
Excellent question. Going to the second page is easy! Simply add &page=2
to your request. In the second tab, you will see that the meta description changes accordingly.
Do you want the API to return more or fewer results per page? That’s also possible! You can determine the number of results per page (range 10-150) by adding &per_page= {number}
to your request. For example, if you want 110 results per page:
Just like before, the meta description changes accordingly.
For an overview of which endpoints support pagination, please refer to our API Reference Guide.
Note that including a substantial amount of relationships might result in failed responses due to memory limits.
We need to protect the uptime of our API and therefore, you might hit the memory limit of 2GB when requesting too much data at a time.
Now that you know all about pagination, we can explore our API’s endless possibilities with the next chapter: enriching your response.
Code number
Description
200
Successful request and data was returned
400
Part of the request is malformed; the exact reason can be found in the response
401
Request is not authenticated
403
Unauthorized request to access data from an ineligible plan
429
You have reached the response rate limit of your plan
500
Internal error with our servers
Field
Description
data
Opens an array of data you've requested
id
A unique league id
active
Indicates if the league is active or not. Possible values are 'true' or 'false'
type
Indicates what kind of league this is. Possible values: 'domestic', 'cup', 'international'. More values can be found here
legacy_id
This was for our API version 1.0. It's only of use for old users of our API
country_id
The unique country id the league is played in
logo_path
The logo URL path of the league
name
The name of the league
is_cup
Indicates if the league is a cup or not. Possible values are 'true' or 'false'
current_season_id
The unique id of the current season
current_round_id
The unique id of the current round
current_stage_id
The unique id of the current stage
live_standings
Indicates if the league covers live standings
coverage
Opens an array of partial coverage for the league
predictions
Indicates if the league covers predictions
topscorers_goals
Indicates if the league covers goal topscorers
topscorers_assists
Indicates if the league covers assists topscorers
topscorers_cards
Indicates if the league covers cards topscorers
Field
Description
pagination
Opens an array of information about the pages in the API response
total
The total amount of results the API returns
count
The amount of results on the current page
per_page
The amount of results per page
current_page
The number of page currently browsed
total_pages
The total number of pages
links
The link if you want to go to the next API page
Field
Description
pagination
Opens an array of information about the pages in the API response
total
The total amount of results the API returns
count
The number of results on the current page
per_page
The number of results per page
current_page
The number of pages currently browsed
total_pages
The total number of pages
links
The link if you want to go to the next API page
Field
Description
pagination
Opens an array of information about the pages in the API response
total
The total amount of results the API returns
count
The amount of results on the current page
per_page
The amount of results per page
current_page
The number of page currently browsed
total_pages
The total number of pages
links
The link if you want to go to the next API page
We'll teach you how to personalize your request. The first thing on the to-do list is to display different time zones. After all, having the data displayed in your preferred time zone would be pretty convenient, right?
All of our dates and times are displayed in UTC by default. However, most applications indicate the times in their relevant time zones, such as CEST and PST.
You wouldn’t want to frustrate your clients by sending them the times of matches in the central European time zone when they live in Australia, now would you?
That’s why we’ve made it easy for you to get all the dates and times in whatever time zone you prefer.
“How do I do that?“
Easy! Simply override the default time zone (UTC) with the parameter called: tz
.
In this tutorial, we’ll be adding the ‘tz
’ parameter to a request with the livescores endpoint. This will result in the following URL:
And just like that, we've successfully requested the data to be returned in the Asian/Singaporean time zone instead of the default UTC. There are a lot more time zones available. You can find a list of valid time zones on Wikipedia.
When you’ve parsed an invalid time zone, you’ll get the error code 400
. For an overview of all error codes see our response code page.
Now that you’ve successfully changed the time zone to your desired one, we can move on to explore the next part of our tutorial series, which is about pagination.
Note that changing the timezone currently does not change the results queried from the databases. It only changes the time attributes.
Welcome to Sportmonks’ Football API. We have designed the API for iGaming, media, developers and football enthusiasts. Sportmonks ensures that you can create a football application that meets your wishes and needs.
Football API 2.0 is a REST API that can be used to request football data from our wide-ranging database and has the following characteristics:
Highly customizable requests
Incredibly fast livescores
Reliable and accurate data
You will find valuable tutorials and how-to guides to help you kickstart your application on these documentation pages. Let's get started right away by making your first request!
We recommend you submit your requests with Postman since we have already prepared the request for you there! Hit the button below to import our Football API collection.