SWU Stats

Star Wars Unlimited Stats
Pull down to refresh
SWU Stats APIs

SWU Stats APIs

Welcome to the SWU Stats API documentation. This page provides information about available APIs. Please note that some APIs may have rate limits or require authentication. For high-volume usage, please contact us to discuss your needs. There is no charge to use SWU Stats APIs, but we ask that you visibly credit SWU Stats on your site if you use them. If you have any questions or need assistance with our APIs, please join our Discord server.

Deck Statistics API

Access statistical information about decks, including win rates, matchups, and more.

Get Deck Statistics

GET /TCGEngine/Stats/DeckMetaStatsAPI.php

Retrieve statistics for decks based on different parameters.

Query Parameters:

Parameter Type Description
deckId integer The ID of the deck to retrieve stats for
startWeek integer (Optional) Start week (inclusive). If omitted and endWeek omitted, defaults to week = 0 (historical/current week depending on server config).
endWeek integer (Optional) End week (inclusive). If provided together with startWeek, returns the inclusive range between them.
format string (Optional) Filter by game format

Example Response:

{
    "leaderID": "0524529055",
    "leaderTitle": "Snap Wexley",
    "leaderSubtitle": "Resistance Recon Expert",
    "baseID": "1029978899",
    "baseTitle": "Colossus",
    "baseSubtitle": "",
    "numPlays": 42,
    "winRate": "66.67",
    "avgTurnsInWins": "7.76",
    "avgTurnsInLosses": "8.36",
    "avgCardsResourcedInWins": "8.02",
    "avgRemainingHealthInWins": "12.28"
}

Deck Edit API

Modify a deck you own (add or remove cards). This endpoint requires OAuth authentication with the 'decks' scope and the caller must be the deck owner.

Edit Deck Card

POST /TCGEngine/APIs/EditDeckCard.php

Authentication:

This endpoint requires an OAuth access token. Provide the token via one of the following:

Request Body (JSON):

{
    "access_token": "your_oauth_token",    // or provide in Authorization header
    "deckID": 123,                          // integer deck id
    "action": "add|remove",               // add or remove
    "cardID": "CARD_UID",                 // card id used in gamestate
    "count": 1,                             // number to add/remove (optional, default 1)
    "zone": "main|side"                   // zone to change (optional, default "main")
}

Example Responses:

Success (HTTP 200)
POST /TCGEngine/APIs/EditDeckCard.php
{
    "success": true,
    "deckID": 123,
    "action": "remove",
    "cardID": "CARD_UID",
    "zone": "main",
    "removed": 1
}
Missing or Invalid Token (HTTP 401)
{
    "success": false,
    "errors": {
        "access_token": "Missing access token"
    }
}
// or
{
    "success": false,
    "errors": {
        "access_token": "Invalid or expired"
    }
}
Not Owner (HTTP 403)
{
    "success": false,
    "error": "Not deck owner"
}
Card Not Present (HTTP 404)
{
    "success": false,
    "error": "Card not found in specified zone"
}

All Matchup Statistics API

Retrieve all matchup statistics across all leader/base combinations. Useful for bulk analysis or building aggregated views.

Get All Matchup Statistics

GET /TCGEngine/APIs/MetaMatchupStatsAPI.php

Returns every row from the deckmetamatchupstats table for the current week (week = 0).

Query Parameters:

Parameter Type Description
None — This endpoint does not accept query parameters; it returns all rows for week = 0.

Example Response:

[
    {
        "leaderID": "0524529055",
        "baseID": "1029978899",
        "opponentLeaderID": "1234567890",
        "opponentBaseID": "0987654321",
        "numWins": 12,
        "numPlays": 30,
        "playsGoingFirst": 15,
        "turnsInWins": 90,
        "totalTurns": 210,
        "cardsResourcedInWins": 80,
        "totalCardsResourced": 200,
        "remainingHealthInWins": 45,
        "winsGoingFirst": 7,
        "winsGoingSecond": 5
    }
    // More matchup objects...
]

Deck Matchup Statistics API

Access detailed matchup statistics for a specific deck (leader + base combination) against all other decks.

Get Deck Matchup Statistics

GET /TCGEngine/APIs/DeckMetaMatchupStatsAPI.php

Retrieve matchup statistics for a deck, showing how it performs against other leader/base combinations.

Query Parameters:

Parameter Type Description
leaderID string The ID of the leader for the deck
baseID string The ID of the base for the deck

Example Response:

[
    {
        "opponentLeaderID": "1234567890",
        "opponentBaseID": "0987654321",
        "numWins": 12,
        "numPlays": 30,
        "playsGoingFirst": 15,
        "turnsInWins": 90,
        "totalTurns": 210,
        "cardsResourcedInWins": 80,
        "totalCardsResourced": 200,
        "remainingHealthInWins": 45,
        "winsGoingFirst": 7,
        "winsGoingSecond": 5
    }
    // More matchup objects...
]

Card Statistics API

Access statistical information about individual cards, including play rates, resource rates, and more.

Get Card Statistics

GET /TCGEngine/Stats/CardMetaStatsAPI.php

Retrieve statistics for individual cards based on different parameters.

Query Parameters:

Parameter Type Description
cardId string The ID of the card to retrieve stats for
startWeek integer (Optional) Start week (inclusive). If omitted and endWeek omitted, defaults to week = 0.
endWeek integer (Optional) End week (inclusive). If provided together with startWeek, returns the inclusive range between them.
format string (Optional) Filter by game format

Example Response:

{
    "cardId": "CARD123",
    "name": "Example Card",
    "timesIncluded": 1500,
    "timesPlayed": 850,
    "timesResourced": 420,
    "playRate": 56.7,
    "resourceRate": 28.0,
    "winRateWhenPlayed": 62.3
}

Game Submission API

Submit game results to be included in our statistics database. An API key is required to use this endpoint. Reach out on Discord to get an API key.

Submit Game Result

POST /TCGEngine/APIs/SubmitGameResult.php

Request Body:

{
    "apiKey": "your_api_key",  // Your API key
    "winner": 1,               // 1 for player 1, 2 for player 2
    "firstPlayer": 1,          // 1 for player 1, 2 for player 2
    "round": 10,               // Number of turns/rounds played
    "winnerHealth": 5,         // Health remaining for winner
    "winHero": "Red Hero",     // Winner's hero/leader
    "loseHero": "Blue Hero",   // Loser's hero/leader
    "winnerDeck": "Deck List", // Winner's deck contents
    "loserDeck": "Deck List",  // Loser's deck contents
    "player1": "{...}",        // Player 1 stats JSON
    "player2": "{...}",        // Player 2 stats JSON
    "p1DeckLink": "https://swustats.net/path/to/deck?gameName=1234",
    "p2DeckLink": "https://swustats.net/path/to/deck?gameName=5678",
    "p1id": "player1_id",      // Optional player IDs
    "p2id": "player2_id",
    "format": "premier",       // Optional: game format (default: "premier"). Examples: "premier", "preview"
    "disableMetaStats": false, // Optional: set to true if one or more players opts out of meta stats collection
    "gameName": "12345",       // Game identifier
    "sequenceNumber": 1        // Optional sequence number for BO3 matches
}

Player Stats JSON Format:

The player stats JSON contains detailed information about a player's performance in the game, including card usage and turn-by-turn statistics.

{
    "gameId": "12345",              // Unique game identifier (optional)
    "gameName": "match_12345",      // Custom game name (optional)
    "deckId": "NextTurn.php?gameName=1787&playerID=1&folderPath=SWUDeck", // The last part of the deck link
    "leader": "12345",              // Leader id (FFG UID format)
    "base": "12345",                // Base id (FFG UID format)
    "turns": 8,                     // Number of turns played
    "result": 1,                    // 1 if this player won, 0 for loss
    "firstPlayer": 1,               // 1 if this player went first, 0 otherwise
    "opposingHero": "12345",        // Opponent's leader id (FFG UID format)
    "opposingBaseColor": "Red",     // Opponent's base color (Red, Blue, Yellow, Green, Colorless)
    "deckbuilderID": "user_42",     // Deckbuilder user ID
    "cardResults": [
        {
            "cardId": "12345",      // Card id (FFG UID format)
            "played": 1,            // Times played
            "resourced": 1,         // Times used as resource
            "activated": 2,         // Times ability activated
            "drawn": 2,             // Times drawn
            "discarded": 0          // Times discarded
        },
        // More cards...
    ],
    "turnResults": [
        {
            "cardsUsed": 3,         // Cards played this turn
            "resourcesUsed": 4,     // Resources spent
            "resourcesLeft": 0,     // Resources remaining
            "cardsLeft": 2,         // Cards left in hand
            "damageDealt": 5,       // Damage dealt this turn
            "damageTaken": 3        // Damage received this turn
        },
        // More turn results...
    ]
}

Example Response:

Success (HTTP 200)
{
    "success": true,
    "gameResultID": 12345
}
Invalid/Expired Tokens (HTTP 401)

If one or more provided SWU OAuth tokens are invalid or expired the API returns a 401 with a structured errors object describing which token(s) failed.

{
    "success": false,
    "errors": {
        "p1SWUStatsToken": "Invalid or expired",
        "p2SWUStatsToken": "Invalid or expired"
    }
}

Melee Tournaments API

Access information about Melee tournaments including tournament details, links, and dates.

Get Melee Tournaments

GET /TCGEngine/APIs/GetMeleeTournaments.php

Retrieve a list of Melee tournaments with optional filtering and pagination.

Query Parameters:

Parameter Type Description
id integer (Optional) Specific tournament ID to retrieve
limit integer (Optional) Maximum number of tournaments to return (default: 50)
offset integer (Optional) Number of tournaments to skip for pagination (default: 0)
date_from string (Optional) Filter tournaments after this date (YYYY-MM-DD)
date_to string (Optional) Filter tournaments before this date (YYYY-MM-DD)
sort string (Optional) Sort tournaments by field and direction (e.g., "tournamentDate DESC", default: "tournamentDate DESC")
format string (Optional) Response format: "json" or "html" (default: "json")

Example Response:

{
    "success": true,
    "total": 42,
    "count": 20,
    "offset": 0,
    "limit": 20,
    "tournaments": [
        {
            "id": 1,
            "name": "Star Wars: Unlimited Sector Qualifier - Milan, Italy | Melee",
            "date": "2025-03-30",
            "link": 270771,
            "melee_url": "https://melee.gg/tournament/270771"
        },
        // More tournaments...
    ]
}

Get Melee Tournament Details

GET /TCGEngine/APIs/GetMeleeTournament.php

Retrieve detailed information for a specific Melee tournament, including standings, matchups, and player statistics.

Query Parameters:

Parameter Type Description
id integer (Required) The ID of the tournament to retrieve details for
include_matchups integer (Optional) Set to 1 to include detailed matchup data (default: 0)

Example Response:

{
    "success": true,
    "tournament": {
        "id": 1,
        "name": "Star Wars: Unlimited Sector Qualifier - Milan, Italy | Melee",
        "date": "2025-03-30",
        "link": 270771,
        "round_id": 977630,
        "melee_url": "https://melee.gg/tournament/270771"
    },
    "decks_count": 32,
    "decks": [
        {
            "id": 1,
            "player": "PlayerName",
            "meleeId": 123456,
            "rank": 1,
            "standings": {
                "match_record": "7-0-0",
                "match_wins": 7,
                "match_losses": 0,
                "match_draws": 0,
                "match_win_rate": 100,
                "game_record": "14-2-0",
                "game_wins": 14,
                "game_losses": 2,
                "game_draws": 0,
                "game_win_rate": 87.5
            },
            "points": 21,
            "tiebreakers": {
                "omwp": 68.57,
                "tgwp": 87.5,
                "ogwp": 65.24
            },
            "matchups": [
                {
                    "opponent_id": 5,
                    "opponent_name": "OpponentName",
                    "wins": 2,
                    "losses": 0,
                    "draws": 0,
                    "result": "2-0-0"
                },
                // More matchups...
            ]
        },
        // More decks/players...
    ]
}

Deck API

Access and manage deck information.

Get User Decks

GET /TCGEngine/APIs/UserAPIs/GetUserDecks.php

Retrieve a list of decks owned by the authenticated user, including those marked as favorites. This API requires OAuth authentication with the 'decks' scope.

Authentication:

This endpoint requires OAuth 2.0 authentication with the 'decks' scope. The access token must be provided in one of the following ways:

Query Parameters:

Parameter Type Description
limit integer (Optional) Maximum number of decks to return (default: 100)
offset integer (Optional) Number of decks to skip for pagination (default: 0)
sort string (Optional) Sort field: 'name' or 'date' (default: 'name')
order string (Optional) Sort order: 'asc' or 'desc' (default: 'asc')
favorites string (Optional) Set to 'true' to only return favorite decks

Example Response:

{
    "decks": [
        {
            "id": 123,
            "name": "My Favorite Deck",
            "description": "A powerful deck for tournaments",
            "visibility": 1,
            "created_at": "2025-01-01 12:00:00",
            "updated_at": "2025-04-20 15:30:00",
            "is_favorite": true
        },
        {
            "id": 456,
            "name": "Another Deck",
            "description": "Casual play deck",
            "visibility": 2,
            "created_at": "2025-02-15 09:30:00",
            "updated_at": "2025-04-18 14:15:00",
            "is_favorite": false
        }
    ],
    "pagination": {
        "total": 42,
        "limit": 100,
        "offset": 0,
        "has_more": false
    }
}

Load Deck

GET /TCGEngine/APIs/LoadDeck.php

Load a deck by its ID.

Query Parameters:

Parameter Type Description
deckID integer The ID of the deck to load

Example Response:

{
    "deckId": 12345,
    "name": "Example Deck",
    "hero": "Red Hero",
    "cards": [
        {
            "cardId": "CARD123",
            "count": 3
        },
        // More cards...
    ]
}