17lands API17lands.com ↗
Access 17lands card win rates, color archetype performance, trophy decklists, and player leaderboards for MTG Arena draft formats via a structured API.
What is the 17lands API?
The 17lands API exposes 5 endpoints covering Magic: The Gathering Arena draft analytics, including per-card win rate statistics, archetype color ratings, and 7-win trophy decklists. The get_card_ratings endpoint returns over 10 performance fields per card — including avg_seen, avg_pick, win_rate, drawn_improvement_win_rate, and play_rate — filterable by expansion, format, rarity, color, date range, and user skill group.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/185c7f2c-c4bb-4543-804e-36c6f657bb81/get_filters' \ -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 17lands-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: 17lands Draft Analytics — find the best archetype and cards."""
from parse_apis.lands17 import (
Lands17, Format, UserGroup, Rarity, CloudflareBlocked
)
client = Lands17()
# Fetch available metadata to discover current expansions and formats.
filters = client.filters.get()
print(f"Latest expansion: {filters.expansions[0]}, formats: {filters.formats[:3]}")
# List card ratings for a specific expansion filtered by rarity.
for card in client.cardratings.list(
expansion="FDN", format=Format.PREMIER_DRAFT, rarity=Rarity.RARE, limit=5
):
print(f" {card.name}: WR={card.win_rate:.1%}, pick={card.avg_pick:.1f}")
# List color archetype performance to find winning pairs.
for archetype in client.colorratings.list(
expansion="FDN", format=Format.PREMIER_DRAFT, user_group=UserGroup.TOP, limit=5
):
print(f" {archetype.color_name} ({archetype.short_name}): {archetype.wins}W / {archetype.games}G")
# Browse recent trophy decks (7-win runs).
deck = client.trophydecks.list(expansion="FDN", format=Format.PREMIER_DRAFT, limit=1).first()
if deck:
print(f"Trophy deck: {deck.colors}, record {deck.wins}-{deck.losses}, rank {deck.start_rank}")
# Fetch the leaderboard and inspect the top winner.
try:
board = client.leaderboards.get(expansion="FDN", format=Format.PREMIER_DRAFT)
top = board.wins[0]
print(f"Top player: {top.screen_name}, {top.wins} wins, {top.win_rate:.1%} WR")
except CloudflareBlocked:
print("Temporarily blocked by Cloudflare — retry later")
print("exercised: filters.get / cardratings.list / colorratings.list / trophydecks.list / leaderboards.get")
Returns all available expansions, formats, and other filter metadata for constructing queries to other endpoints. A singleton resource — no parameters required. Contains expansion codes, format names, color identifiers, user skill groups, start dates per expansion, and which formats are currently live.
No input parameters required.
{
"type": "object",
"fields": {
"colors": "array of color filter values (null, W, U, B, R, G)",
"groups": "array of user skill group values (null, bottom, middle, top)",
"formats": "array of format names (PremierDraft, TradDraft, QuickDraft, etc.)",
"expansions": "array of expansion codes ordered by recency",
"start_dates": "object mapping expansion codes to their start date timestamps",
"ranked_formats": "array of format names that have ranked play",
"formats_by_expansion": "object mapping expansion codes to their available formats",
"live_formats_by_expansion": "object mapping currently active expansion codes to their live formats"
},
"sample": {
"data": {
"colors": [
null,
"W",
"U",
"B",
"R",
"G"
],
"groups": [
null,
"bottom",
"middle",
"top"
],
"formats": [
"PremierDraft",
"TradDraft",
"QuickDraft",
"Sealed"
],
"expansions": [
"SOS",
"Y26SOS",
"TMT",
"ECL",
"FDN"
],
"start_dates": {
"FDN": "2024-11-12T15:00:00Z",
"SOS": "2026-04-21T15:00:00Z"
},
"ranked_formats": [
"BotDraft",
"PremierDraft",
"QuickDraft"
],
"formats_by_expansion": {
"FDN": [
"PremierDraft",
"TradDraft",
"QuickDraft"
]
},
"live_formats_by_expansion": {
"SOS": [
"PremierDraft",
"TradDraft"
]
}
},
"status": "success"
}
}About the 17lands API
Card and Color Performance Data
The get_card_ratings endpoint returns per-card draft statistics for a given expansion and format. Each record includes avg_seen (average pick position when a card is seen in a pack), avg_pick (average pick position when taken), win_rate (game win rate when the card is in the deck), ever_drawn_win_rate, and drawn_improvement_win_rate — the delta in win rate between games where the card was drawn versus games where it sat in the deck. Filters include expansion, format, colors, rarity, user_group (top/middle/bottom), and a start_date/end_date window. Use get_filters first to retrieve valid values for all of these parameters, including available expansion codes and which formats are live right now.
Color Archetype and Trophy Data
get_color_ratings breaks down win/loss records by deck color combination — mono-color through five-color, including splash variants. Each row returns wins, games, color_name, short_name (e.g. WU, BR), and is_summary. The combine_splash boolean collapses splash variants into their base pair for cleaner comparison. The get_trophy_decks endpoint (POST) lists 7-win draft runs with deck metadata: colors, end_rank, start_rank, wins, losses, time, and an aggregate_id for identifying the deck. It accepts filters for ranks, deck_colors, and card_names, but only returns data for currently active or recent expansions.
Leaderboard and Filter Discovery
get_leaderboard returns the top players segmented into five categories — rank, wins, trophies, win_rate, and trophy_rate — each as an array of player entries filterable by expansion and format. The get_filters endpoint acts as a metadata registry: it returns all valid expansion codes, format names, formats_by_expansion, live_formats_by_expansion, and start_dates mapped to each expansion. Call it once to build any query against the other four endpoints.
The 17lands API is a managed, monitored endpoint for 17lands.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 17lands.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 17lands.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?+
- Identify the highest
drawn_improvement_win_ratecards in a new MTG set to find signal cards worth prioritizing in draft - Compare
win_ratebyuser_group(top vs bottom) to detect cards that overperform for skilled players - Track color archetype strength across a format's lifespan using
start_date/end_datefilters onget_color_ratings - Filter
get_trophy_decksbydeck_colorsandcard_namesto study how top-ranked players build specific archetypes - Build a draft tier list app that refreshes daily card ratings per expansion and format from
get_card_ratings - Display leaderboard data segmented by
trophy_rateandwin_ratecategories fromget_leaderboardin a player stats dashboard - Use
get_filtersto automatically discover newly released expansions and their active formats without hardcoding values
| 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 17lands have an official developer API?+
What does `drawn_improvement_win_rate` actually measure in `get_card_ratings`?+
Does `get_trophy_decks` return full decklists with card-by-card contents?+
colors, wins, losses, start_rank, end_rank, time, and aggregate_id. It also returns a has_draft flag indicating whether pick-by-pick draft data is associated with the run. Individual card contents of a trophy deck are not included in the response. You can fork this API on Parse and revise it to add a deck detail endpoint if you need card-level data.Are older expansion sets available through `get_trophy_decks`?+
get_card_ratings and get_color_ratings cover a broader historical window via their start_date/end_date parameters.Does the API cover Constructed or other non-draft MTG Arena formats?+
get_filters. Constructed format data is not included. You can fork this API on Parse and revise it to add endpoints targeting Constructed data if 17lands publishes it.