API DE STORMGATE

This document describes the HTTP endpoints and methods that make up the public API for various Stormgate datasets provided by Untapped.gg.

USAGE LIMITS

You are free to access these APIs without authentication. There is a rate limit of no more than 20 requests per minute to any of the public API endpoints. If you have a use case that needs a higher request limit, please email data@frostgiant.com.

Note that due to Cross-Origin Resource Sharing protections you will need to run your own proxy or script to fetch the data from this API. We will not consider whitelist requests at this time.

LEADERBOARD

Returns the top 500 players by points, descending for the specified ranked match mode.

Positions on the leaderboard are updated on a 1 minute period.

URL PARAMETERS

matchMode: Supported values: ranked_1v1

GET https://api.stormgate.untapped.gg/api/v1/leaderboard?match_mode={matchMode}

Response

[
  {
    "race": "infernals",
    "points": 2530,
    "wins": 343,
    "losses": 15,
    "ties": 0,
    "league": "master",
    "tier": 1,
    "mmr": 2513,
    "playerName": "HorsePasta",
    "profileId": "At4X3hJ"
  },
  …
]

PLAYER SEARCH

Retrieve information about Stormgate players by display name.

If the search term includes the # character, a full match will be performed against the player's display name and discriminator.

Otherwise, a match will be performed against the player's full display name, not including discriminator, and all records with a matching display name will be returned.

URL PARAMETERS

q: Player display name query. Case-insensitive. Must exactly match player name.

GET https://api.stormgate.untapped.gg/api/v1/players?q={displayName}

Response

[
  {
    "playerName": "HorsePasta",
    "profileId": "At4X3hJ",
    "ranks": {
      "ranked_1v1": {
        "infernals": {
          "mmr": 2513,
          "tier": 1,
          "ties": 0,
          "wins": 343,
          "league": "master",
          "losses": 15,
          "points": 2530,
          "season": 1
        }
      }
    }
  },
  …
]

PLAYER LOOKUP

Retrieve basic information across all game modes about a single Stormgate player. Only ranked_1v1 is fully populated at this time.

URL PARAMETERS

profileId: The Untapped.gg profile id. Profile ids can be found via the Leaderboard or Player Search APIs.

GET https://api.stormgate.untapped.gg/api/v1/players/{profileId}

Response

{
  "playerName": "HorsePasta",
  "profileId": "At4X3hJ",
  "ranks": {
    "ranked_1v1": {
      "infernals": {
        "mmr": 2513,
        "tier": 1,
        "ties": 0,
        "wins": 343,
        "league": "master",
        "losses": 15,
        "points": 2530,
        "season": 1
      }
    }
  }
}

PLAYER STATS

Retrieve a detailed stats summary about a single Stormgate player, identified by Untapped.gg profile id. The response contains an entry for each "meta period" (usually a balance patch, see Meta Periods) within the season, indentified by the metaPeriodId, as well as an "all" entry for the entire season.

URL PARAMETERS

profileId: Profile ids can be found via the Leaderboard or Player Search APIs.
matchMode: Supported values: ranked_1v1
season: Supported values: current

FIELDS

recent_mmr_history: MMR at the end of the match, most recent first.
outcomes_by_duration: Outcomes by minute, rounded up, for each opponent faction.
outcomes_by_opponent: Outcomes against the most frequent opponents. Ordered by total match count, then recency.
outcomes_by_opponent_race: Outcomes against each opposing faction overall.
outcomes_by_map: Outcomes on each map overall.
summary: Total stats and rank. For meta periods that have ended these will reflect the state at the end of that meta period.

GET https://api.stormgate.untapped.gg/api/v2/matches/players/{profileId}/stats/{matchMode}?season={season}

Response

{
  "2": {
    "celestials": {
      "recent_mmr_history": [
        2237,
        2230,
        ...
      ],
      "outcomes_by_duration": {
        "celestials": [
          {
            "minute": 3,
            "wins": 4,
            "losses": 1,
            "ties": 0
          },
          {
            "minute": 4,
            "wins": 5,
            "losses": 2,
            "ties": 0
          },
        ],
      },
      "outcomes_by_opponent": [
        {
          "player_name": "PastaHorse",
          "profile_id": "Jh3X4tA",
          "race": "celestials",
          "wins": 11,
          "losses": 4,
          "ties": 0
        },
      ],
      "outcomes_by_opponent_race": {
        "celestials": {
          "wins": 29,
          "losses": 10,
          "ties": 0
        },
      },
      "outcomes_by_map": {
        "SecludedGroveV2": {
          "wins": 12,
          "losses": 2,
          "ties": 0
        },
      },
      "summary": {
        "points": 2160,
        "wins": 65,
        "losses": 14,
        "ties": 0,
        "league": "master",
        "tier": 1,
        "mmr": 2237
      }
    },
  },
  "3": { ... },
  "all": { ... }
}

PLAYER RECENT MATCHES

Retrieve the most recent 100 matches per faction for a single Stormgate player, identified by Untapped.gg profile id. This will only return matches if the player has set their match history to be public. Otherwise this API will return a 403 error code.

URL PARAMETERS

profileId: Profile ids can be found via the Leaderboard or Player Search APIs.
matchMode: Supported values: ranked_1v1
season: Supported values: current

GET https://api.stormgate.untapped.gg/api/v2/matches/players/{profileId}/recent/{matchMode}?season={season}

Response

{
  "vanguard": [
    {
      "match_id": "j7QEn454kNo3SUkYhe3KoZ",
      "mode": "ranked_1v1",
      "season": 1,
      "map_name": "IsleOfDread",
      "match_start": 1724676527,
      "match_active_seconds": 622,
      "match_total_seconds": 661,
      "players": [
        {
          "player_name": "HorsePasta",
          "player_number": 1,
          "profile_id": "At4X3hJ",
          "party": 0,
          "team": 0,
          "race": "vanguard",
          "outcome": "loss",
          "previous_ranking": {
            "points": 1318,
            "wins": 11,
            "losses": 10,
            "ties": null,
            "league": "bronze",
            "tier": 1,
            "mmr": 1756
          },
          "updated_ranking": {
            "points": 1324,
            "wins": 11,
            "losses": 11,
            "ties": null,
            "league": "bronze",
            "tier": 1,
            "mmr": 1737
          }
        },
        {
          "player_name": "PastaHorse",
          "player_number": 2,
          "profile_id": "Jh3X4tA",
          "party": 1,
          "team": 1,
          "race": "celestials",
          "outcome": "win",
          "previous_ranking": { ... },
          "updated_ranking": { ... }
        }
      ]
    },
  ],
  "infernals": [ ... ],
  "celestials": [ ... ],
}

META PERIODS

Retrieve all meta periods. A meta period describes a certain range of time that is used to group data about the game. These commonly correspond to game patches, though they don't strictly have to.

GET https://api.stormgate.untapped.gg/api/v1/meta-periods

Response

[
  {
    "id": 4,
    "description": "Patch 0.0.2",
    "match_mode": "ranked_1v1",
    "start_client_version": "70039",
    "start_ts": "2024-08-22T21:00:00Z",
    "end_ts": null
  },
  {
    "id": 3,
    "description": "Patch 0.0.1",
    "match_mode": "ranked_1v1",
    "start_client_version": "69129",
    "start_ts": "2024-08-08T17:45:00Z",
    "end_ts": "2024-08-22T21:00:00Z"
  },
]