QFX Mythic Rank Data - US

Overview

QFX Mythic Rank Data - US is a lightweight Mythic+ data provider for the US region.

It provides validated regional Mythic+ score cutoffs, population statistics, achievement thresholds, recent cutoff history, season information, dungeon-pool metadata, score color tiers, and estimated regional ranking data through a public Lua API.

This is a data-only addon intended for addon developers and WeakAura authors. It does not provide its own visual interface.

Region

Region: United States
Region code: us

Main Features

• US-region Mythic+ score cutoff data
• Five published percentile cutoff points
• All-faction, Horde, and Alliance population data
• Faction-specific cutoff colors
• Mythic+ achievement score thresholds
• Recent 30-day cutoff history
• Current season information
• Current Mythic+ dungeon pool
• Dungeon Challenge Mode IDs
• Dungeon timer information
• Keystone bracket levels
• Season remapping status
• Raider.IO score color tiers
• Estimated regional rank calculations
• Public Lua API Version 2
• Compatible with addons and WeakAuras
• Can be installed together with the CN, EU, TW, and KR regional packages

Lightweight Data-Only Addon

This addon creates no:

• Frames
• Display elements
• Settings panels
• Minimap buttons
• Game-event listeners
• Timers
• OnUpdate handlers
• SavedVariables

It does not require the in-game Raider.IO addon.

Other addons and WeakAuras can use the public Lua API to create their own displays.

Data Source

Data is obtained from Raider.IO’s public Mythic+ API.

The database uses normalized source data from:

• Mythic+ static season data
• Regional season cutoffs
• Raider.IO score tiers

All source responses are validated before replacing the existing US-region database.

Invalid, incomplete, or inconsistent source data does not overwrite the last known-good regional data.

Database States

The regional database exposes both status and seasonState.

Ready

status = "ready"
seasonState = "active"
available = true

The Mythic+ season is active and validated score cutoff data is available.

Collecting

status = "collecting"
seasonState = "active"
available = false
population = 0
cutoffs = {}

The season is active, but valid cutoff data has not formed yet.

This state may occur during the protected startup period at the beginning of a new season.

Offseason

status = "offseason"
seasonState = "upcoming"

or:

status = "offseason"
seasonState = "ended"

No Mythic+ season is currently active.

The package retains metadata for the nearest upcoming or most recently ended season, but does not expose stale population or ranking data.

Important Ranking Notice

Rank results are estimates calculated from Raider.IO’s published percentile cutoff points.

They are not exact character leaderboard positions and should always be presented as estimated ranks or rank ranges.

This data package does not contain:

• Player names
• Realm names
• Complete leaderboards
• Dungeon-run members
• Character equipment
• Character talents
• Class statistics
• Exact character ranking positions

Public Lua API

The shared global API object is:

local API = QFXMythicRankData

Current API version:

API.apiVersion == 2

Recommended compatibility check:

local API = QFXMythicRankData

if not API or (tonumber(API.apiVersion) or 0) < 2 then
    return
end

Supported Region

us

Supported Factions

all
horde
alliance

When the faction argument is omitted or invalid, the API uses all.

Supported Cutoff Keys

p999
p990
p900
p750
p600

The API returns cutoff entries in this order.

Basic API Example

local API = QFXMythicRankData

if API
    and API.apiVersion >= 2
    and API:IsRegionAvailable("us")
then
    local metadata = API:GetMetadata("us")
    local cutoff = API:GetCutoff("us", "p990", "all")
    local estimate = API:EstimatePlayerRank("us", "all")

    if cutoff then
        print("US p990 score:", cutoff.score)
        print("Players at or above cutoff:", cutoff.rank)
    end

    if estimate then
        print("Estimated regional rank:", estimate.estimatedRank)
    end
end

API Method Reference

API:GetCurrentRegion()

Returns the current World of Warcraft client region.

local region = API:GetCurrentRegion()

Possible results:

"cn"
"us"
"eu"
"tw"
"kr"
nil

API:IsRegionAvailable(region)

Returns whether validated ranking data is currently available.

local available = API:IsRegionAvailable("us")

Returns true only when:

• The US regional package is loaded
• The database status is ready
• available is true
• Valid cutoff data exists

Returns false during collecting and offseason.

API:GetRegionData(region)

Returns the complete registered regional database table.

local data = API:GetRegionData("us")

Returns the raw regional table or nil.

Consumer addons should treat the returned table as read-only.

Use the dedicated API methods whenever possible.

API:GetMetadata(region)

Returns regional metadata.

local metadata = API:GetMetadata("us")

Returned fields may include:

{
    region = "us",
    available = true,
    season = "season-mn-1",
    updatedAt = "Source update timestamp",
    source = "Raider.IO",
    sourceURL = "https://raider.io",
    population = 1500000,
    dataVersion = "202607161450",
    status = "ready",
    seasonState = "active",
    schemaVersion = 2,

    populationByFaction = {
        all = 1500000,
        horde = 800000,
        alliance = 700000,
    },

    isRemappedSeason = false,
}

Optional source fields may be absent.

API:GetPopulation(region, faction)

Returns the regional population for the selected faction.

local total = API:GetPopulation("us", "all")
local horde = API:GetPopulation("us", "horde")
local alliance = API:GetPopulation("us", "alliance")

Returns a number or nil.

During collecting and offseason, population is normally 0.

API:GetSeasonInfo(region)

Returns normalized season metadata.

local season = API:GetSeasonInfo("us")

Returned fields may include:

{
    slug = "season-mn-1",
    name = "Season Name",
    shortName = "Short Name",

    -- Optional
    blizzardSeasonID = 17,

    isMainSeason = true,

    -- UTC Unix timestamps in seconds
    startsAt = 1774479600,
    endsAt = 1797548400,

    dungeons = {
        -- Dungeon entries
    },

    -- Optional
    seasonalAffix = {
        id = 123,
        name = "Affix Name",
        icon = "icon-name",
    },
}

Notes:

• startsAt and endsAt are UTC Unix timestamps in seconds.
• blizzardSeasonID may be absent.
• seasonalAffix may be absent.
• During offseason, the table may describe the nearest upcoming or most recently ended season.

API:GetSeasonDungeons(region)

Returns the selected season’s dungeon pool.

local dungeons = API:GetSeasonDungeons("us")

Each dungeon entry contains:

{
    id = 6988,
    challengeModeID = 161,
    slug = "skyreach",
    name = "Skyreach",
    shortName = "SKY",
    timerSeconds = 1800,
}

Fields:

• id: Raider.IO dungeon ID
• challengeModeID: Blizzard Challenge Mode ID
• slug: dungeon slug
• name: full dungeon name
• shortName: abbreviated dungeon name
• timerSeconds: dungeon timer in seconds

Returns a table or nil.

API:GetCutoff(region, key, faction)

Returns one percentile cutoff entry.

local cutoff = API:GetCutoff("us", "p990", "all")

Returned structure:

{
    key = "p990",
    quantile = 0.99,
    score = 3967.15,
    rank = 15751,
    population = 1574971,
    percentile = 1.0001,
    color = "#ea6078",
}

Fields:

• key: cutoff key
• quantile: Raider.IO source quantile
• score: minimum score at the cutoff
• rank: population count at or above the cutoff
• population: selected faction population
• percentile: selected population percentage
• color: Raider.IO cutoff color for the selected faction

Returns nil when the cutoff is unavailable.

API:GetCutoffs(region, faction)

Returns all available percentile cutoff entries.

local cutoffs = API:GetCutoffs("us", "all")

Returned order:

p999
p990
p900
p750
p600

Returns an empty table when cutoff data is unavailable.

API:GetAchievementCutoff(region, key, faction)

Returns a Mythic+ achievement threshold and corresponding regional statistics.

Supported achievement keys:

keystoneLegend
keystoneHero
keystoneMaster
keystoneConqueror
keystoneExplorer

Example:

local achievement = API:GetAchievementCutoff(
    "us",
    "keystoneMaster",
    "all"
)

Returned fields may include:

{
    key = "keystoneMaster",
    thresholdScore = 2000,
    quantile = 0.25,
    score = 2000,
    rank = 250000,
    population = 1000000,
    percentile = 25,
    color = "#a335ee",
}

Returns nil when Raider.IO does not provide the requested achievement node.

API:GetCutoffHistory(region, key)

Returns recent Raider.IO cutoff history.

local history = API:GetCutoffHistory("us", "p990")

Each history point contains:

{
    timestampMs = 1784077800000,
    score = 3967.15,

    -- Optional
    population = 1574971,
}

Notes:

• timestampMs is a UTC Unix timestamp in milliseconds.
• population is optional.
• Points are ordered from oldest to newest.
• The package stores source history from approximately the latest 30 days.
• The package does not calculate daily changes or trends.

Returns a table or nil.

API:GetScoreTiers(region)

Returns Raider.IO score color thresholds.

local tiers = API:GetScoreTiers("us")

Each entry contains:

{
    score = 4000,
    color = "#ff8000",
}

Entries are ordered from highest score to lowest.

Returns a table or nil.

API:GetBracketDungeonLevels(region)

Returns the source-provided keystone bracket levels.

local levels = API:GetBracketDungeonLevels("us")

Example:

{
    2,
    4,
    7,
    10,
    12,
}

Values are ordered from lowest to highest.

Returns a table or nil.

API:GetPlayerScore()

Returns the current player’s Blizzard Mythic+ score.

local score = API:GetPlayerScore()

Returns a number or nil.

API:EstimateRank(region, score, faction)

Estimates a US-region rank from a supplied score.

local result, errorMessage = API:EstimateRank(
    "us",
    3500,
    "all"
)

Returned structure may contain:

{
    region = "us",
    score = 3500,
    faction = "all",

    bracket = "p900-p750",

    rankMin = 150000,
    rankMax = 400000,
    estimatedRank = 245000,

    percentileMin = 10,
    percentileMax = 25,

    isEstimate = true,
    updatedAt = "Source update timestamp",
}

For a score below the lowest published cutoff:

estimatedRank = nil

The API still returns the known outer rank and percentile range.

Possible errors:

invalid score
region data unavailable
cutoff data unavailable

The result must be presented as an estimated rank, not an exact leaderboard position.

API:EstimatePlayerRank(region, faction)

Reads the current player’s Blizzard Mythic+ score and estimates the regional rank.

local result, errorMessage = API:EstimatePlayerRank(
    "us",
    "all"
)

When region is omitted, the current client region is used.

Possible additional error:

player score unavailable

API:RegisterCallback(owner, callback)

Registers a callback that runs when a regional data package registers its data.

local function OnRegionRegistered(owner, region, data)
    print("Regional data loaded:", region)
end

API:RegisterCallback(MyAddon, OnRegionRegistered)

Callback signature:

callback(owner, region, data)

Returns true when registration succeeds.

API:UnregisterCallback(callback)

Removes a previously registered callback.

API:UnregisterCallback(OnRegionRegistered)

Returns true for a valid callback function.

API:RegisterRegion(region, data)

Registers a regional database with the shared API.

This method is used internally by the official QFX Mythic Rank Data regional packages.

Consumer addons and WeakAuras should not call this method or replace official regional data.

Developer Recommendations

• Check API.apiVersion before using Version 2 methods.
• Check API:IsRegionAvailable("us") before estimating ranks.
• Treat returned regional database tables as read-only.
• Handle optional source fields safely.
• Treat collecting and offseason as valid states.
• Do not present estimated ranks as exact positions.
• Refresh displays when a registration callback is received.
• Multiple regional data packages may be installed simultaneously.