Getting started

Pandascore's live API is a WebSocket-based API that allows you to receive real-time data from eSports events.

This documentation refers to the latest version of the API (2.3).

This guide is intended to get you up and running with real-world applications based on the Pandascore live API. It will cover everything you need to know about our API, from authentication to actually receiving data.

The Pandascore's live API is often referred to as the
Live API,
in contrast to the REST API.

Overview

The Live API publishes events related to matches. First, it is necessary to understand how the data is structured.

These are the two main types of data published by the API:

Tournaments
which are esports events involving players or teams competing, often hold into a single venue. The duration of the tournament can be as short as a weekend or spans over several months.

Matches
which are often composed of multiple games (unless performed in
best-of-one
format), which involves two teams or players. It includes a winner and a loser, determined by the result of the individual games of the match.

Pandascore provides esports data in two forms: static and live.

Static data

Static data is available through our API.
With
HTTP requests,
you can obtain any of our prematch or post-match
(Fixture and Historical data plan or higher)
data.
Access is granted through the use of your personal token which is uniquely generated for you.

When making an HTTP request, you can provide your
token
in one of two ways, either directly in the URL:

https://api.pandascore.co/lol/champions.json?token=YOUR_TOKEN

Or through the use of the
Authorization header.

This is primarily to simplify the integration of our API into your own programs and applications, and not really intended for manual use.
However, it can be easily tested in your terminal: with
curl
you can set headers by using the
-H
flag.

Please browse our API documentation for further information and use cases.

Live data

Available only to those with the Basic live plan and up, live data is handled quite differently from static data.

The data is sent to you in real time during the progression of a match, and cannot be recovered or repeated once the event has ended.
The basic summary of the match, of course, can be found in our API once the event has ended. The real-time data feed is delivered from a WebSocket endpoint.

Through these WebSockets we send data in packets called frames. Each frame is a snapshot of the match.

As you can see, the response consists of event/endpoint pairs,
which provide information on the different live matches,
as well as how to connect to them (
url
). Endpoints can be "frames" or "events".

"Frames" endpoints send you frames of the current state of the running match over time, while "Events" endpoints are
play-by-play
feeds sending you events of what's currently happening during the match (ex: a played has been killed, a tower has been destroyed etc...).
"Events" endpoints are currently only available for League of Legends, and require the
Pro Live plan.
We will talk again about "Events" endpoints later.

As events 'warm up' they will be made available regardless of their
begin_at
.
It is possible to connect to the WebSockets for events before they begin, to test the connection and prepare for the first frame.

Further information on the matches in the list can be obtained using the
match_id
:

https://api.pandascore.co/matches/MATCH_ID.json?token=YOUR_TOKEN

Live plan

The
Pro Live plan
differs from the
Basic Live plan
in a few ways.

First, those with the
Pro Live plan
receive more detailed live data: the
Basic Live plan
WebSockets work the same way, but the
Pro Live plan
offers more in-depth data.
More data will be added to the
Pro Live plan
live feed as we perfect new features.

Furthermore, the
Pro Live plan
gives you access to the play-by-play feed, which is a second WebSocket parallel to the main WebSocket for each match.

This feed will not send frames with the "snapshot" of the current game, instead describing key
"events"
when they occur, such as player kills, towers/inhibitors destructions, nashors/herald kills, etc.

As this feed describes more and more events over time for each game,
it will effectively provide a play-by-play in real time for all matches we support.

Authentication

Access to our APIs is restricted by a token-based authentication. In other words, your account is associated with a unique secret key that is required to connect to the API endpoints. You can find your API token on your
account page.

In order to identify you, we will require you to send your token with every HTTP request you make. This can be achieved in two different ways. You can either set it in the Authorization request header (e.g.
Authorization: Bearer YOUR_TOKEN),
or you can include it directly in the token parameter of the URL (e.g.
https://live.pandascore.co/some-url?token=YOUR_TOKEN
).

This token is private, be careful not to use it in client-side applications.

Replace YOUR_TOKEN with your own API token. If you don't have one, you will first need to
create an account.

We included your API token in all the examples, so feel free to copy-paste to try them right away!
Don't worry, only you can see its value.

Fetching the events

Before connecting to the WebSockets, you first have to fetch the list of available events.

The list of tournaments that are currently running can be retrieved at the following endpoint:
https://api.pandascore.co/lives?token=YOUR_TOKEN

We can see that there is only one event running right now. Along with it, we can find a list of endpoints associated with this event. There is one endpoint for each match being played at the moment, each one of them having a unique
url
attribute. In our example, there is only one endpoint available for this event.

In the next section, we will see how to connect to one of these URLs.

Connecting to the Websockets

Now that we have our match URL, it is time to actually connect to the Websocket. As seen previously, there is a match associated with the URL
wss://live.pandascore.co/matches/8191?token=YOUR_TOKEN,
so we will try to connect to this endpoint.

The URL we use was available at the time this guide was written, which is probably not the case by now. Do not forget to replace it by a valid URL.

You can perform secure connections to Websockets via shell commands or with your preferred language. The following examples showcase usage of both the
wscat
command and the Javascript language.