Getting started

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

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.

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.

This API allows you to access real-time data by either subscribing to events from specific matches.

Authentication

Access to the Live API 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 your 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.

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

Example

curl https://api.pandascore.co/lives?token=YOUR_TOKEN

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[ { "event": { "id": 40, "game": "league-of-legends", "begin_at": "2017-05-03T20:00:00.000+02:00", "end_at": "2017-05-07T15:28:55.244+02:00", "is_active": false, "tournament_id": 359 }, "endpoints": [ { "url": "wss://live.pandascore.co/matches/8191", "id": 8191, "last_active": null, "open": false, "begin_at": "1970-01-18T06:57:14.000+00:00", "match_id": 8191 } ] } ]

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.

Example (with wscat)

wscat -c wss://live.pandascore.co/matches/8191

Example (with Javascript)

var socket = new WebSocket('wss://live.pandascore.co/matches/8191');
socket.onmessage = function(event) {
	console.log(JSON.parse(event.data))
}

Response

{"type":"hello","payload":{}}

If it is your first connection, the server will send you a hello event, indicating that everything went well and that you are successfully connected and waiting for new events.

From this point, you will only receive stream events. They happen on a frequence ranging from 2 to 10 seconds, depending on the in-game actions. These events describe the current state of the match.