RoyaleAPI APIroyaleapi.com ↗
Access Clash Royale player profiles, battle history, clan details, leaderboards, popular decks, and card stats via the RoyaleAPI API. 7 structured endpoints.
What is the RoyaleAPI API?
This API provides structured Clash Royale game data across 7 endpoints, pulling from RoyaleAPI.com. The get_player_profile endpoint returns a player's current trophies, best trophies, league, clan affiliation, and a full stats object by player tag. Other endpoints cover battle history, clan membership, global or regional leaderboards up to 1000 entries, popular decks ranked by win rate, individual card statistics, and active tournaments.
curl -X GET 'https://api.parse.bot/scraper/9af24979-f7eb-4daa-954f-804732926ed6/get_player_profile?player_tag=J0VU9CGP' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace royaleapi-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: RoyaleAPI SDK — Clash Royale competitive analysis, bounded and re-runnable."""
from parse_apis.royaleapi_scraper import (
RoyaleAPI, TimeRange, LeaderboardType, NotFound
)
client = RoyaleAPI()
# Fetch top global players from the leaderboard.
for ranking in client.rankings.leaderboard(type=LeaderboardType.PLAYERS, limit=5):
print(ranking.rank, ranking.name, ranking.score, ranking.clan)
# Drill into one player's profile and recent battles.
player = client.players.get(player_tag="J0VU9CGP")
print(player.name, player.trophies, player.current_league)
for battle in player.battles(limit=3):
print(battle.result, battle.type, battle.time)
# Look up the player's clan.
try:
clan = client.clans.get(clan_tag="RU0Y02JV")
print(clan.name, len(clan.members), "members")
except NotFound:
print("clan not found")
# Browse popular decks for the last 7 days.
for deck in client.decks.popular(time_range=TimeRange.SEVEN_DAYS, limit=3):
print(deck.cards, deck.stats.win_rate)
# List top cards by usage.
card = client.cards.list(limit=1).first()
if card:
print(card.name, card.usage, card.win_rate)
# Check active tournaments.
for tournament in client.tournaments.list(limit=3):
print(tournament.name, tournament.players, tournament.status, tournament.open)
print("exercised: rankings.leaderboard / players.get / player.battles / clans.get / decks.popular / cards.list / tournaments.list")
Get player statistics and profile info from RoyaleAPI. Returns the player's name, trophies, league, clan affiliation, and detailed gameplay statistics. The stats object contains key-value pairs scraped from the player's profile page (total games, wins, donations, account age, etc.).
| Param | Type | Description |
|---|---|---|
| player_tagrequired | string | Player tag with or without leading # (e.g. J0VU9CGP or #J0VU9CGP). |
{
"type": "object",
"fields": {
"tag": "string, player tag without #",
"clan": "object with name and tag, or null if not in a clan",
"name": "string, player display name",
"stats": "object containing gameplay statistics (key-value pairs)",
"trophies": "string, current trophy count",
"best_trophies": "string, personal best trophy count",
"current_league": "string, current league name"
},
"sample": {
"data": {
"tag": "J0VU9CGP",
"clan": {
"tag": "GC8UG2YC",
"name": ""
},
"name": "Dominik",
"stats": {
"max_wins": "20",
"account_age": "9y 25w 2d",
"total_games": "5,156",
"three_crown_wins": "17,473"
},
"trophies": "11549",
"best_trophies": "11576",
"current_league": "Summit of Heroes"
},
"status": "success"
}
}About the RoyaleAPI API
Player and Clan Data
The get_player_profile endpoint accepts a player tag (with or without the leading #) and returns fields including name, trophies, best_trophies, current_league, and a stats object with detailed gameplay key-value pairs. The clan field is either an object with name and tag or null for clanless players. The get_player_battles endpoint returns a battles array where each entry includes the battle result, type, timestamp, and participant data for the queried player_tag.
The get_clan_details endpoint takes a clan_tag and returns the clan's name, description, and a full members array. Each member entry includes name, tag, role, trophies, and level, making it straightforward to build clan comparison tools or roster trackers.
Decks, Cards, and Leaderboards
The get_popular_decks endpoint accepts an optional time_range parameter (1d, 3d, 7d, 14d, or 28d) and returns up to 20 deck objects. Each deck contains a cards array of card slug strings and a stats object with win_rate and rating. The get_card_stats endpoint requires no inputs and returns all cards sorted by popularity, each with a name, usage percentage, and win_rate percentage.
The get_leaderboard endpoint supports filtering by type (players or clans) and region (global or a country code such as us, kr, or de). It returns up to 1000 ranked entries, with player entries including clan and level fields and clan entries including members and location. The get_tournaments endpoint requires no inputs and lists current and recent tournaments with name, tag, players (formatted as current/max), status, and an open boolean.
The RoyaleAPI API is a managed, monitored endpoint for royaleapi.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when royaleapi.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official royaleapi.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display a player's current league, trophy count, and best trophies on a Clash Royale stat dashboard using
get_player_profile. - Analyze a player's recent win/loss pattern by iterating over the
battlesarray fromget_player_battles. - Surface the top-rated decks for a given time window using
get_popular_deckswith thetime_rangeparameter. - Build a card tier list ordered by win rate using the
usageandwin_ratefields fromget_card_stats. - Generate a clan roster page showing each member's role, level, and trophies via
get_clan_details. - Show country-specific player or clan rankings by passing a country code to
get_leaderboard. - List open tournaments with available slots by filtering
get_tournamentsresults on theopenboolean andplayersfield.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does RoyaleAPI have an official developer API?+
What does the leaderboard endpoint return for players versus clans?+
rank, name, tag, and score. Player entries additionally include clan affiliation and level. Clan entries include members count and location. Pass type=players or type=clans and an optional region (e.g. us, kr, or global) to filter results.Does the API return a player's full card collection or chest cycle?+
get_player_profile endpoint returns trophy counts, league, clan, and a gameplay stats object, but does not expose the player's card collection, upgrade levels, or chest cycle state. You can fork this API on Parse and revise it to add an endpoint covering that data.How fresh is the battle history returned by `get_player_battles`?+
Can I retrieve deck statistics for a specific card combination rather than the global popular decks list?+
get_popular_decks endpoint returns up to 20 decks ranked by rating across a chosen time range, but does not accept a card filter to look up stats for an arbitrary deck. You can fork this API on Parse and revise it to add a custom deck lookup endpoint.