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.
    League of Legends includes the leagues: EU LCS, NA LCS, LCK, etc.
  • Series belong to a league. They are composed of one or several tournaments.
    The League of Legends' EU LCS league includes the series: Spring Slit 2017, Summer Split 2017, etc.
  • Tournaments belong to a series. They are composed of one or severals matches.
    The League of Legends' EU LCS Summer Split 2017 includes the tournaments: 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.

Making your first request

Now, you have everything you need to call the API from 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 default, and that we can specify a page[number] parameter (or, more simply, the page parameter), in order to navigate through 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}, (...)]

For more information about the number of items, the current page, or the links to the next, last, first and previous pages, we can look to 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 number of items per page.
X-Total The total count of items across all pages.
X-Runtime The execution time 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 endpoints can return a maximum of 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 by one or more fields for one or more 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 their names matching exactly either 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, and they are applied in the order specified.

The sort order for each sort field is ascending unless 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 strongest to the weakest. All champions with the same armor value will then be sorted by name in ascending alphabetical order.

Ranges

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

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

Searches

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

For example, to get all the champions with a name containing "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,
    ...
  }
]