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.

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.

curl -H 'Authorization: Bearer YOUR_TOKEN' 'https://api.pandascore.co/lol/champions.json'

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.

{
  "blue": {
    "gold": 41300,
    "acronym": "RNG",
    "herald": 1,
    "drakes": 2,
    "nashors": 0,
    "inhibitors": 0,
    "towers": 4,
    "name": "Royal Never Give Up",
    "players": {
      "top": {
        "items": [
          {
            "id": 686,
            "name": "Warding Totem (Trinket)"
          },
          null,
          {
            "id": 608,
            "name": "Stopwatch"
          },
          {
            "id": 831,
            "name": "Ionian Boots of Lucidity"
          },
          {
            "id": 736,
            "name": "Needlessly Large Rod"
          },
          {
            "id": 795,
            "name": "Shurelya's Reverie"
          },
          {
            "id": 821,
            "name": "Morellonomicon"
          }
        ],
        "level": 13,
        "hp": 98,
        "champion": {
          "id": 685,
          "name": "Vladimir",
          "image_url": IMAGE_URL
        },
        "assists": 2,
        "name": "Zz1tai",
        "cs": 195,
        "kills": 1,
        "id": 368,
...

When you first connect to a WebSocket you will receive a confirmation frame similar to this:

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

This confirms that your connection was a success, and you will receive all future frames for this event.


A list of ongoing matches can be obtained from this API call:

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

This call will respond in the following manner, which we will break down further:

[{
    "event": {
      "id": 22,
      "game": null,
      "begin_at": "2017-02-24T07:00:00Z",
      "end_at": "2017-02-26T13:59:28Z",
      "tournament_id": 224,
      "is_active": false
    },
    "endpoints": [{
      "url": "wss://live.pandascore.co/matches/3219",
      "last_active": null,
      "type": "frames",
      "open": true,
      "begin_at": "2018-03-29T13:00:12.000+00:00",
      "match_id": 3219
    }, {
      "url": "wss://live.pandascore.co/matches/3219/events",
      "last_active": null,
      "type": "events",
      "open": true,
      "begin_at": "2018-03-29T13:00:12.000+00:00",
      "match_id": 3219
    }]
  },
  {
    "event": {
      "id": 22,
      "game": null,
      "begin_at": "2017-02-24T07:00:00Z",
      "end_at": "2017-02-26T13:59:28Z",
      "tournament_id": 224,
      "is_active": false
    },
    "endpoints": [{
      "url": "wss://live.pandascore.co/matches/3220",
      "last_active": null,
      "type": "frames",
      "open": true,
      "begin_at": "2018-04-13T12:35:42.000+00:00",
      "match_id": 3220
    }]
  }
]

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.

{
  "type": "kill_feed",
  "payload": {
    "type": "tower",
    "killer": {
      "type": "player",
      "object": {
        "id": 2508,
        "name": "Ning",
        "team": "red",
        "role": "jun",
        "champion": {
          "id": 693,
          "name": "Zac"
        }
      }
    },
    "killed": {
      "type": "tower",
      "object": {
        "name": "tower blue",
        "team": "blue"
      }
    }
  },
  "match": {
    "id": 38670
  },
  "game": {
    "id": 182803
  },
  "ingame_timestamp": 954,
  "ts": 1524827233278,
  "id": "470eb9f9a18387ed6a9c3a9fd24112d5"
}

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.

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?token=YOUR_TOKEN

Example (with Javascript)

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.

Send us your feedback

Thank you for your feedback!

We will get back to you as soon as possible.

Further communication will be conducted by email.

A problem has occurred.

This call has encountered an error:
Please email support@pandascore.co directly.