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.

🔑 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.

🗓️ 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
wscat -c 'wss://live.pandascore.co/matches/8191?token=YOUR_TOKEN'
var socket = new WebSocket('wss://live.pandascore.co/matches/8191?token=YOUR_TOKEN');
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.

Websocket endpoints

Two different websocket endpoints exist: Frames, which are available for all video games, and Events, for CS:GO and League of Legends only.

🎞️ Frames Websockets

Frames represent the latest state of the game, and are updated every two seconds. They are available at wss://live.pandascore.co/matches/:match_id .

Frames contain the side of each team, which is crucial to always have updated as it will help you handle the Events Websockets easier.

Scoreboard Example Frames can help you build displays of the current state of the game.

💥 Events Websockets

Events represent the timeline of the game. They are available at wss://live.pandascore.co/matches/:match_id/events.

If you happen to miss some frames, you can recover them (read more about it here)

Timeline Example Events can help you build timelines of the game history.

← Getting StartedCS:GO →