@varandas/clash-royale-api
Version:
A Clash Royale API official wrapper for seamless integration with your applications.
264 lines (209 loc) • 9.23 kB
Markdown
<p align="center">
<img src="https://raw.githubusercontent.com/AndreVarandas/clash-royale-api/master/art/logo.png" width="400" height="260" alt="Clash Royale Official API Wrapper logo">
</p>
# Clash Royale Official API Wrapper
[](https://www.npmjs.com/package/@varandas/clash-royale-api)
[](https://npmcharts.com/compare/@varandas/clash-royale-api)
[](https://travis-ci.org/AndreVarandas/clash-royale-api)
[](https://codecov.io/gh/AndreVarandas/clash-royale-api/)
[](https://github.com/semantic-release/semantic-release)
[](https://snyk.io/test/github/AndreVarandas/clash-royale-api?targetFile=package.json)
[](https://github.com/AndreVarandas/clash-royale-api/blob/master/LICENSE)
An asynchronous wrapper for the official Clash Royale API.
Official API Link [https://developer.clashroyale.com](https://developer.clashroyale.com)
## Important note
This wrapper will only work from a nodejs server app. The official clash royale api is, unfortunately, blocking requests done directly from the browser.
## Getting started
In order to use the official api, you will need a token. This token can be obtained at the Official API website [https://developer.clashroyale.com](https://developer.clashroyale.com). - For each token an ip address is associated, so make sure to use the token in the same server where you got it.
You can also use a **proxy server** to make the requests, such as [https://docs.royaleapi.com/proxy.html](https://docs.royaleapi.com/proxy.html) - More details below in the usage section.
Once you register and get the token, you are ready to start.
## Usage
Install the package:
- `yarn add /clash-royale-api`
OR
- `npm i --save /clash-royale-api`
Usage:
```javascript
// Import the package
const { ClashRoyaleAPI } = require('/clash-royale-api')
// Initialize the api
const api = new ClashRoyaleAPI('the token you got from the api')
// Use the api to get cards
api
.getCards()
.then(cards => {
// Do something with the cards
})
.catch(err => {
// handle errors
})
// Using the proxy server (https://proxy.royaleapi.dev/v1)
// Create a key on the the official API and whitelist (include) this IP: 45.79.218.79
// Use https://proxy.royaleapi.dev/v1
const api = new ClashRoyaleAPI(
'the token you got from the api',
'https://proxy.royaleapi.dev/v1',
)
// Use the api to get cards
...
```
## About the proxy server
The proxy server is a service provided by the RoyaleAPI team. It allows you to make requests to the official API from the browser.
If you want to host your own proxy server, there is a nuxt web app you can use available at [https://github.com/AndreVarandas/royale-proxy-api](https://github.com/AndreVarandas/royale-proxy-api).
## Methods
All api calls are asynchronous and used in the same way as above in the getCards example.
**Clans**
- `getClans(params: IClanRequestParams)` - Returns a list of all the available clans.
- `getClanByTag(tag: string)` - Returns details about a specific clan.
- `getClanMembers(tag: string)` - Returns a list of clan members.
- `getClanWarlog(tag: string)` - Returns the war log for a clan
- `getClanCurrentWar(tag: string)` - Retrieve information about clan's current clan war
- `getClanCurrentRiverRace(tag: string)` - Retrieve information about clan's current river race
**Players**
- `getPlayerByTag(tag: string)` - Get information about a single player by player tag.
- `getPlayerUpcomingChests(tag: string)` - Get list of reward chests that the player will receive next in the game.
- `getPlayerBattleLog(tag: string)` - Get list of recent battle results for a player.
**Tournaments**
- `getTournaments(params: ITournamentRequestParams)` - Search all tournaments by name.
- `getTournamentByTag(tag: string)` - Get information about a single tournament by a tournament tag.
- `getGlobalTournaments` - List all available global tournaments.
**Cards**
- `getCards` - Get list of all available cards.
**Locations**
- `getLocations(params: ILocationRequestParams)` - List all available locations.
- `getLocationById(id: string, params: ILocationFullRequestParams)` - Get information about specific location.
- `getClanRankinsForLocation(id: string, params: ILocationFullRequestParams)` - Get clan rankings for a specific location.
- `getPlayerRankingsForLocation(id: string, params: ILocationFullRequestParams)` - Get player rankings for a specific location.
- `getClanWarRankingsForLocation(id: string, params: ILocationFullRequestParams)` - Get clan rankings for a specific location.
**Leaderboards**
- `getLeaderboards()` - List leaderboards for different trophy roads.
- `getLeaderboardById(leaderboardId: number, params: ILeaderboardRequestParams)` - Get players on a specific leaderboard.
## Configuration Objects
**IClanRequestParams**
```typescript
/**
* Note:
* Only the name property is required.
*/
export interface IClanRequestParams {
/**
* Search clans by name.
* If name is used as part of search query, it needs to be at least three
* characters long. Name search parameter is interpreted as wild card
* search, so it may appear anywhere in the clan name.
*/
name: string
/**
* Filter by clan location identifier. For list of available locations,
* refer to getLocations operation.
*/
locationId?: number
/**
* Filter by minimum amount of clan members.
*/
minMembers?: number
/**
* Filter by maximum amount of clan members.
*/
maxMembers?: number
/**
* Filter by minimum amount of clan score.
*/
minScore?: number
/**
* Limit the number of items returned in the response.
*/
limit?: number
/**
* Return only items that occur after this marker.
* After marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
after?: number
/**
* Return only items that occur before this marker.
* Before marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
before?: number
}
```
**ITournamentRequestParams**
```typescript
/**
* Note:
* Only the name property is required.
*/
export interface ITournamentRequestParams {
/**
* Search tournaments by name.
*/
name: string
/**
* Limit the number of items returned in the response.
*/
limit?: number
/**
* Return only items that occur after this marker.
* After marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
after?: number
/**
* Return only items that occur before this marker.
* Before marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
before?: number
}
```
**ILocationRequestParams**
```typescript
export interface ILocationRequestParams {
/**
* Limit the number of items returned in the response.
*/
limit?: number
/**
* Return only items that occur after this marker.
* After marker can be found from the response,
* inside the 'paging' property. Note that only
* after or before can be specified for a request, not both.
*/
after?: number
/**
* Return only items that occur before this marker.
* Before marker can be found from the response,
* inside the 'paging' property. Note that only
* after or before can be specified for a request, not both.
*/
before?: number
}
```
**ILeaderboardRequestParams**
```typescript
export interface ILeaderboardRequestParams {
/**
* Limit the number of items returned in the response.
*/
limit?: number
/**
* Return only items that occur after this marker.
* After marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
after?: string
/**
* Return only items that occur before this marker.
* Before marker can be found from the response, inside the 'paging' property.
* Note that only after or before can be specified for a request, not both.
*/
before?: string
}
```
[LICENSE - MIT](LICENSE)
---
## Credits
Logo by [Caneco](https://twitter.com/caneco).
---
This content is not affiliated with, endorsed, sponsored, or specifically approved by Supercell and Supercell is not responsible for it. For more information see [Supercell’s Fan Content Policy](http://www.supercell.com/fan-content-policy).