Classic and Season of Discovery API Support in Azeroth Auction Assassin: Implementation Guide

Azeroth Auction Assassin supports Classic and Season of Discovery (SOD) APIs through region-specific namespaces, faction-filtered endpoints, and static data fallbacks, but requires different region identifiers and disables Undermine Exchange integration for these game modes.

Azeroth Auction Assassin (AAA) is an open-source auction house scanner built primarily for the Blizzard Retail API. However, the codebase includes comprehensive support for Classic and Season of Discovery API interactions, requiring specific architectural adjustments to handle differing endpoints, namespaces, and data availability. This guide examines the implementation details, configuration requirements, and limitations when operating in Classic or SOD modes.

Region and Namespace Configuration for Classic APIs

Valid Region Identifiers

Unlike Retail regions (EU, NA), Classic and Season of Discovery require distinct region strings to differentiate API endpoints. The valid identifiers are:

• EUCLASSIC – European Classic realms
• NACLASSIC – North American Classic realms
• NASODCLASSIC – North American Season of Discovery
• EUSODCLASSIC – European Season of Discovery

In utils/mega_data_setup.py, the WOW_REGION variable is validated against this specific list at lines 60-71. If the region string contains "CLASSIC", the system triggers Classic-specific logic paths for namespace construction and faction handling.

Dynamic Namespace Construction

Blizzard's API uses different namespaces for Retail versus Classic data. The construct_api_url() method in utils/mega_data_setup.py (lines 49-53) dynamically builds the correct namespace:

• Season of Discovery: Uses dynamic-classic1x-<region> (e.g., dynamic-classic1x-eu)
• Classic Era: Uses dynamic-classic-<region> (e.g., dynamic-classic-eu)

The logic checks for "SOD" in the region string first, then falls back to standard Classic namespace construction if "CLASSIC" is detected.

Faction-Specific Auction Endpoints

Classic APIs expose auction data through faction-specific endpoints rather than the unified Retail endpoint. In utils/mega_data_setup.py (lines 11-21), the get_ah_data() method constructs endpoint arrays based on the FACTION configuration:

• /2 – Alliance auctions
• /6 – Horde auctions
• /7 – Neutral (Auction House) auctions

For Classic regions, the system iterates through these endpoints to aggregate complete auction house data. The FACTION variable defaults to "all" for Classic modes, ensuring all three endpoints are queried unless specifically filtered.

Data Source Limitations and Fallbacks

Undermine Exchange and Wowhead Link Handling

Classic and Season of Discovery realms do not provide data to Undermine Exchange, and Wowhead links are unreliable for these game versions. When utils/mega_data_setup.py detects a Classic region (lines 64-70), it automatically:

• Forces WOWHEAD_LINK to True (enabling Wowhead links despite limitations)
• Sets FACTION to "all" if not already specified
• Disables Undermine Exchange integration

This ensures users receive at least minimal external linking functionality while acknowledging the data availability constraints of Classic APIs.

Static Data Fallback Mechanisms

Classic endpoints are marked by Blizzard as less stable and may return errors or temporary unavailability. To ensure continuous operation, utils/api_requests.py (lines 91-103) implements comprehensive fallback logic:

All external API calls—including item names, pet names, and update timers—are wrapped in try/except blocks. If the primary API fails, the system retrieves static JSON files stored in the repository's StaticData/ directory via raw GitHub URLs.

This fallback mechanism is critical for Classic support, as it allows the scanner to continue operating using cached data when Blizzard's Classic API experiences downtime.

Russian Realm Filtering

Classic data may include Russian realms that users wish to exclude from scanning. The get_wow_russian_realm_ids() function in utils/helpers.py (lines 26-30) returns a comprehensive list including Classic-specific realm IDs (4452, 4474).

When NO_RUSSIAN_REALMS is enabled, these IDs are filtered from update timers and auction data retrieval, ensuring Russian Classic realms are excluded from market analysis.

UI and Configuration Requirements

Region Selection Interface

The graphical interface must expose Classic and Season of Discovery options to users. In AzerothAuctionAssassin.py (lines 49-58), the region selection combo box is populated with the full suite of supported regions:

region_options = [
    "EU", "NA", 
    "EUCLASSIC", "NACLASSIC", 
    "NASODCLASSIC", "EUSODCLASSIC"
]

This ensures users can select the appropriate game mode without manual configuration file editing.

Configuration File Setup

When initializing MegaData for Classic regions, the constructor automatically adjusts internal state based on the region string. Users must ensure their mega_data.json or environment variables include:

• Valid Classic region identifier in WOW_REGION
• WOWHEAD_LINK will be forced to True automatically
• FACTION will default to "all" if not specified

The system handles namespace conversion and endpoint selection internally, requiring no additional user intervention beyond correct region selection.

Summary

• Region identifiers for Classic and Season of Discovery (EUCLASSIC, NACLASSIC, NASODCLASSIC, EUSODCLASSIC) trigger specialized handling in utils/mega_data_setup.py.
• Namespace construction automatically switches to dynamic-classic or dynamic-classic1x based on region detection.
• Faction-specific endpoints (/2, /6, /7) are required for Classic auction data retrieval, with FACTION defaulting to "all".
• Data limitations force WOWHEAD_LINK to True and disable Undermine Exchange integration for Classic modes.
• Static fallbacks in utils/api_requests.py ensure operation continues when Classic APIs are unstable.
• Russian realm filtering includes Classic-specific IDs (4452, 4474) via utils/helpers.py.

Frequently Asked Questions

Can I use the same API token for Retail and Classic regions?

Yes. The OAuth token flow (/token) is identical across all game modes. The MegaData class obtains a bearer token once via check_access_token() and reuses it for Retail, Classic, and Season of Discovery API calls without requiring separate authentication handling.

Why are Undermine Exchange links disabled for Classic realms?

Undermine Exchange does not provide market data for Classic or Season of Discovery realms. When utils/mega_data_setup.py detects a Classic region, it automatically disables Undermine Exchange integration and forces WOWHEAD_LINK to True to provide at least minimal external item linking functionality, even though Wowhead links are less reliable for Classic versions.

How do I filter out Russian realms in Classic?

Set NO_RUSSIAN_REALMS to true in your configuration. The get_wow_russian_realm_ids() function in utils/helpers.py includes Classic-specific Russian realm IDs (4452, 4474). When enabled, these IDs are excluded from update timer retrieval and auction data processing, ensuring Russian Classic realms are omitted from your market analysis.

What happens if the Classic API is temporarily unavailable?

The system falls back to static JSON files. In utils/api_requests.py, all external API calls are wrapped in try/except blocks. If Blizzard's Classic endpoint returns an error, the scanner retrieves cached data from the StaticData/ directory via raw GitHub URLs, allowing the application to continue operating with potentially stale but functional data until the API recovers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}