API Introduction
The services of the Esports Data Portal also has a common REST API that provides easy integration, bulk download and automated processing of the data. REST API also offers some additional data not available through the UI.
The base URLs of the REST API is:
LoL Data Portal API,
https://lolesports-api.bayesesports.com/v2
Working with the API
To use the API you will need a valid login and password. These are the same credentials you would use to enter the Web UI.
In this section, we will be using curl to demonstrate how to use the Data Portal APIs but there are alternatives:
- using other command-line tools like wget or HTTPie, suitable for quick testing
- using API-clients like Postman or Insomnia, perfect for exploring API endpoints and thorough query testing
- calling APIs directly from your code, the main way of communicating with API for automated data processing
Authentication
Most Data Portal API endpoints require authentication using a bearer token. To authenticate your requests add an HTTP-header using the following format:
Authorization: Bearer <access_token>
The access token is created for you by the authentication server. To generate a new access token, send a POST request to:
POST https://lolesports-api.bayesesports.com/v2/auth/login
with your user login and password in the JSON body. Use the received access token to authenticate your other requests to any of the Data Portal APIs.
An example of an access token request would be the following:
$ curl --request POST \
--url https://lolesports-api.bayesesports.com/v2/auth/login \
--header 'Content-Type: application/json' \
--data '{ "username": "user_email@example.com",
"password": "user_password" }'
The response contains the following JSON (output truncated for brevity):
{
"accessToken":"CI6IkpXVCIsImtp...cYCSEw",
"refreshToken":"v1.MUVzTitZcdL8...VXkVQs",
"expiresIn":86400,
"success":true
}
As the expiresIn response field indicates, the access token accessToken is valid for 24 hours (or 86400 seconds). After this duration you have to authenticate again.
📝 Tip
Issuing a new access token is a slow process. Code that requests a new token before every API call will work much slower than code that stores the token and only refreshes it on expiry. Requesting too many tokens may also be treated as suspicious behavior by the authentication server and potentially result in IP blocks. Click here for more on token reuse.
The other way to get the access token is by sending the refresh token refreshToken from the response above as a POST request to the endpoint:
https://lolesports-api.bayesesports.com/v2/auth/refresh
The refresh token is valid for 30 days but will expire after 15 days of inactivity. Authenticating with the refresh token saves you from the need to send the username and password again. Your app can store the refresh token and extend user sessions without requesting credential input.
Example of refreshing an access token:
$ curl --request POST \
--url https://lolesports-api.bayesesports.com/v2/auth/refresh \
--header 'Content-Type: application/json' \
--data '{ "refreshToken": "v1.MUVzTitZcdL8...VXkVQs" }'
Calling the API
With an access token all endpoints can be called. To see upcoming matches use the following:
$ curl --request GET \
--url https://lolesports-api.bayesesports.com/v2/match/upcoming-matches \
--header 'Authorization: Bearer CI6IkpXVCIsImtp...cYCSEw'
The response will look like this:
{
"totalCount": 92,
"totalPages": 5,
"pageNumber": 0,
"items": [
{
"id": 110422923165247457,
"leagueId": 109545772895506419,
"leagueName": "Arabian League",
"tournamentId": 110422923164198764,
"tournamentName": "Summer 2023",
"type": "normal",
"seriesType": "bestOf",
"seriesMax": 5,
"startTime": "2023-08-08T15:00:00Z",
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"games": [
{
"platformGameId": "110422923165247458",
"esportsGameId": null,
"type": null,
"name": null,
"status": null,
"startedAt": null,
"endedAt": null,
"league": null,
"tournament": null,
"assets": [],
"tags": [],
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"gameVersion": null,
"matchFormat": null,
"state": "UNSTARTED"
},
{
"platformGameId": "110422923165247459",
"esportsGameId": null,
"type": null,
"name": null,
"status": null,
"startedAt": null,
"endedAt": null,
"league": null,
"tournament": null,
"assets": [],
"tags": [],
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"gameVersion": null,
"matchFormat": null,
"state": "UNSTARTED"
},
{
"platformGameId": "110422923165247460",
"esportsGameId": null,
"type": null,
"name": null,
"status": null,
"startedAt": null,
"endedAt": null,
"league": null,
"tournament": null,
"assets": [],
"tags": [],
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"gameVersion": null,
"matchFormat": null,
"state": "UNSTARTED"
},
{
"platformGameId": "110422923165247461",
"esportsGameId": null,
"type": null,
"name": null,
"status": null,
"startedAt": null,
"endedAt": null,
"league": null,
"tournament": null,
"assets": [],
"tags": [],
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"gameVersion": null,
"matchFormat": null,
"state": "UNSTARTED"
},
{
"platformGameId": "110422923165247462",
"esportsGameId": null,
"type": null,
"name": null,
"status": null,
"startedAt": null,
"endedAt": null,
"league": null,
"tournament": null,
"assets": [],
"tags": [],
"teams": [
{
"name": "Anubis Gaming",
"code": "ANB",
"esportsId": "109696073114910519"
},
{
"name": "Nigma Galaxy",
"code": "NGX",
"esportsId": "109696092218588987"
}
],
"gameVersion": null,
"matchFormat": null,
"state": "UNSTARTED"
}
]
},
... // response truncated
]
}
Calling API from code
This code snippet demonstrates how to work with the Data Portal API in Python. This example prints the download url of a game with the content type GAMH_SUMMARY.
📝 Note
This code uses the
get_token.pymodule to get the API access token. This module is described in detail in the Token Reuse section. The placeholder{platform_gameid}in the url should be substituted with a valid platform game id.
list_todays_games.py
import requests
import os
from datetime import datetime
from get_token import get_token
# requesting access token with the help of the get_token.py module
token = get_token()
# creating query string. We want to set "matchDateFrom" to the beginning of today
today = datetime.now()
today = datetime(today.year, today.month, today.day) # truncating time
querystring = {"matchDateFrom": today.isoformat() + 'Z'} # 'Z' stands for UTC
# requesting the /matches endpoint
response = requests.get(
'https://lolesports-api.bayesesports.com/v2/games/{platform_gameid}/download?option=GAMH_SUMMARY',
headers={"Authorization": f"Bearer {token}"},
params=querystring
)
if response.status_code != 200:
response.raise_for_status()
result = response.json()
print("Url to download GAMH_SUMMARY: ", result["url"])
Running the script should produce the following results (The provided URL serves as an illustrative example)
Url to download GAMH_SUMMARY: https://domain.com/gameId/ASIA2WPD2TG7JZQAWVXA%2F20230808%2Feu-1%2Fs3%2Faws4_request