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.
Getting started
Overview
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.
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://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 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.
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?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:
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?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.