Getting started

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

This guide is intended to get you up-and-running with real-world applications based on the Pandascore REST API. We'll cover everything you need to know, from authentication to results manipulation.

Overview

Our API allow you to access data about eSports. We will first take a look at how we structured the data, and summarize the relationship between the three top-level models using the example of Riot Game's League of Legends.

  • Leagues are the top-level models. They are composed of one or several series.
    In the case of League of Legends, they can be: EU LCS, NA LCS, LCK, etc.
  • Series belongs to a league. They are composed of one or several series.
    In the case of League of Legends' EU LCS league, they can be: Spring Slit 2017, Summer Split 2017, etc.
  • Tournaments belongs to a series. They are composed of one or severals matches.
    In the case of League of Legends' EU LCS Summer Split 2017, they can be: Regular Season Group A, Regular Season Group B, Playoffs, etc.

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 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://api.pandascore.co/some-url?token=YOUR_TOKEN ).

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

Make your first request

Now, you have all you need to setup a little basic script using the API trough your application.

Let's try to get all the League of Legends champions :

curl -gi "https://api.pandascore.co/lol/champions.json?token=YOUR_TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Link: <https://api.pandascore.co/lol/champions.json?page=3&token=YOUR_TOKEN>; rel="last", <https://api.pandascore.co/lol/champions.json?page=2&token=YOUR_TOKEN>; rel="next"
X-Page: 1
X-Per-Page: 50
X-Request-Id: c51e8cf0-c397-421c-8a09-44c126f55a36
X-Runtime: 0.077614
X-Total: 133

[{"id":68,"name":"Twitch","armor":23,"armorperlevel":3,"attackdamage":49,"attackdamageperlevel":3,"attackrange":550,"attackspeedoffset":0,"attackspeedperlevel":3,"crit":0,"critperlevel":0,"hp":525,"hpperlevel":81,"hpregen":6,"hpregenperlevel":0,"movespeed":330,"mp":287,"mpperlevel":40,"mpregen":7,"mpregenperlevel":0,"spellblock":30,"spellblockperlevel":0}, (...)]

We can see that our request returned only 50 items, that's because our API is paginated.

Going deeper Pages, filters, ranges, sorts and searches

Pagination

The Pandascore API provides a vast wealth of information for developers to consume. Most of the time, you might even find that you're asking for too much information, and in order to keep our servers happy, the API will automatically paginate the requested items.

The documentation says that the resource is paginated by 50 items by defaut, and that we can specify a page[number] parameter (or, more simpler, the page parameter), in order to navigate trough it. Let's try to fetch the second page:

curl -gi "https://api.pandascore.co/lol/champions.json?page[number]=2&token=YOUR_TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Link: <https://api.pandascore.co/lol/champions.json?page=1&token=YOUR_TOKEN>; rel="first", <https://api.pandascore.co/lol/champions.json?page=1&token=YOUR_TOKEN>; rel="prev", <https://api.pandascore.co/lol/champions.json?page=3&token=YOUR_TOKEN>; rel="last", <https://api.pandascore.co/lol/champions.json?page=3&token=YOUR_TOKEN>; rel="next"
X-Page: 2
X-Per-Page: 50
X-Request-Id: 577fb1bb-a1b2-4ba9-bdc2-c5a3eb82b981
X-Runtime: 0.042902
X-Total: 133

[{"id":126,"name":"Brand","armor":21,"armorperlevel":3,"attackdamage":57,"attackdamageperlevel":3,"attackrange":550,"attackspeedoffset":0,"attackspeedperlevel":1,"crit":0,"critperlevel":0,"hp":507,"hpperlevel":76,"hpregen":5,"hpregenperlevel":0,"movespeed":340,"mp":325,"mpperlevel":45,"mpregen":8,"mpregenperlevel":0,"spellblock":30,"spellblockperlevel":0}, (...)]

To get more informations about the number of items, the current page, or the links to the next, last, first and previous pages, we can have a look on the response headers:

Header name Description
Link The links, if available, to the next, last, previous and first pages.
X-Page The current page.
X-Per-Page The numbers of items on each page.
X-Total The total count of items across all pages.
X-Runtime The time of execution of the request.

You can also increase the number of results returned by the request with the page[size] parameter (or the per_page parameter). Almost all the endpoints can return up to 100 results per page.

Note that page numbering is 1-based and that omitting the page parameter will return the first page.

Filters

The filter query parameter can be used to filter a collection on one or several fields for one or several values. The filter parameter takes the field to filter as a key, and the values to filter as the value. Multiples values must be comma-separated (,).

When using filters, remember that all dates should be given in UTC time. Also, it should be noted that filters work for dates (the day) but not for specific times (hours, minutes or seconds).

For example, to get all the champions with a name matching exactly Twitch or Brand:

curl -gi "https://api.pandascore.co/lol/champions.json?filter[name]=Brand,Twitch&token=YOUR_TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Page: 1
X-Per-Page: 50
X-Request-Id: 35a0a5ed-986a-4d8c-a4ca-9a88adbdc14f
X-Runtime: 0.074479
X-Total: 2
[
  {
    "name": "Brand",
    "armor": 21,
    "armorperlevel": 3,
    "attackdamage": 57,
    ...
  },
  {
    "name": "Twitch",
    "armor": 23,
    "armorperlevel": 3,
    "attackdamage": 49,
    ...
  }
]

Sorts

All index endpoints support multiple sort fields by allowing comma-separated ( , ) sort fields, they are applied in the order specified.

The sort order for each sort field is ascending unless it is prefixed with a minus (U+002D HYPHEN-MINUS, “-“), in which case it is descending.

For example, /lol/champions?sort=-armor,name will return the champions sorted by armor, from the weakest to the strongest. Any champion with the same armor will then be sorted by their name in ascending alphabetical order.

Ranges

The range parameter is a hash allowing filtering for a field, as a key, on two comma-separated bounds. Only the fields between the given bounds will be returned. The bounds are inclusives.

For example, /lol/champions?range[hp]=500,1000 will return all the champions with hit points between 500 and 1000.

Searches

The search parameter is a bit like the filter parameter, but it will return all the results containing the given parameter.

For example, to get all the champions with a name matching "twi":

curl -gi "https://api.pandascore.co/lol/champions.json?search[name]=twi&token=YOUR_TOKEN"
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Page: 1
X-Per-Page: 50
X-Request-Id: 35a0a5ed-986a-4d8c-a4ca-9a88adbdc14f
X-Runtime: 0.074479
X-Total: 2
[
  {
    "name": "Twitch",
    "armor": 23,
    "armorperlevel": 3,
    "attackdamage": 49,
    ...
  },
  {
    "name": "Twisted Fate",
    "armor": 20,
    "armorperlevel": 3,
    "attackdamage": 49,
    ...
  }
]