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.

The PandaScore API allow you to access data about eSports events by using a specific structure.

• Leagues Leagues are the top level events, it doesn’t have a date and represents a regular competition. A League is composed of one or several series.
  Some League of legends leagues are: EU LCS, NA LCS, LCK, etc.
  Some Dota 2 leagues are: ESL One, GESC, The International, PGL, etc.

• Series The Serie represents an occurrence of a league event.
  The EU LCS league has two series per year: spring 2017, summer 2017, spring 2016, summer 2016 etc.
  Some Dota2 Series examples would be: Changsha Major, Open Bucharest, Frankfurt, i-League Invitational etc.

• Tournaments groups all the matches of a serie under "stages" and "groups".
  The tournaments of the EU LCS of summer 2017 are: Group A, Group B, Playoffs, etc.
  Some Dota 2 tournaments are: Group A, Group B, Playoffs, etc.

• And finally, we have the matches , which have two players or teams (depending on the played videogame) and several games (the rounds of the match).
  The matches of the group A in the EU LCS of summer 2017 are: G2 vs FNC, MSF vs NIP, etc.
  The matches of the group A in the ESL One, Genting tournamnet are: Lower Round 1, Quarterfinal, Upper Final, etc.
  Please note that some matches may be listed as "TBD vs TBD" if the matchup is not announced yet, for example the date of the Final match is known but the quarterfinal is still being played.
  

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

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

Now, you have everything you need to call the API from your application.

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

curl -gi "https://api.pandascore.co/lol/champions?token=YOUR_TOKEN"

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Link: <https://api.pandascore.co/lol/champions?page=3&token=YOUR_TOKEN>; rel="last", <https://api.pandascore.co/lol/champions?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.

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?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?page=1&token=YOUR_TOKEN>; rel="first", <https://api.pandascore.co/lol/champions?page=1&token=YOUR_TOKEN>; rel="prev", <https://api.pandascore.co/lol/champions?page=3&token=YOUR_TOKEN>; rel="last", <https://api.pandascore.co/lol/champions?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:

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?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?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,
    ...
  }
]

Conditional requests

Most responses return an ETag and a Last-Modified header. You can use the values of these headers to make subsequent requests to those resources using the If-None-Match and If-Modified-Since headers, respectively. If the resource has not changed, the server will return a 304 Not Modified response code without content.

It's important to notice that making a conditional request and receiving a 304 response does not count as a request on your rate limit.

For example, let's get the running matches:

curl -gi "https://api.pandascore.co/matches/running?token=YOUR_TOKEN"

HTTP/1.1 200 OK
Date: Sun, 04 Mar 2018 15:43:57 GMT
Content-Type: application/json; charset=utf-8
ETag: W/"3b98e557afa6a01b8de29544363870d6"
Last-Modified: Sat, 20 Jan 2018 10:03:15 GMT
X-Rate-Limit-Used: 1
X-Rate-Limit-Remaining: 999
Cache-Control: private, max-age=600
X-Runtime: 0.427772
...
[
  {
    "begin_at": "2018-03-07T09:00:00Z",
    "games": [...],
    "id": 20984,
    "league_id": 294,
    "name": "OMG-vs-TOP",
    "number_of_games": 3,
    ...
  }
]

We can see that our request included an ETag header in the response. Let's try to make the same call, and include the ETag as our If-None-Match request header field:

curl -gi -H 'If-None-Match: W/"3b98e557afa6a01b8de29544363870d6"'  "https://api.pandascore.co/matches/running?token=YOUR_TOKEN"

HTTP/1.1 304 Not Modified
Date: Sun, 04 Mar 2018 16:03:39 GMT
Content-Type: application/json; charset=utf-8
ETag: W/"3b98e557afa6a01b8de29544363870d6"
X-Rate-Limit-Used: 1
X-Rate-Limit-Remaining: 999
Cache-Control: private, max-age=600
X-Runtime: 0.143153
...

As we see, the responses have a 304 HTTP code, and didn't return anything, meaning that nothing changed since our last request. We can also see, with the X-Rate-Limit-Used response header, that this request didn't counted in our rate limit.