Explaining World of Warcraft Auction Snapshots

Posted 2015-08-05 | Billy Overton

In preparation to do some simple analysis on World of Warcraft auction house data, I thought I would take the time to explain some of the data that Blizzard provides through their Battle.Net Community API…with a touch of self-promotion by using the wowapi python library to pull the data in my examples. To use this library, you need an API key from the Battle.net dev site.

On a semi-regular hourly basis, Blizzard publishes snapshots of the current state of each realm’s auction houses. This contains a list of active auctions, pricing information, items being sold, etc.

Connected Realms

When you retrieve data from an auction house, it can contain data for several realms. In 2013, Blizzard started connecting lower population realms together in order to support more active communities. These connected realms share a common auction house, so retrieving a snapshot for one realm will return data for all realms in that set.

Which realms are connected can be seen in the realm status API result. The status contains a lot of information about a realm such as PvP zone status, server timezone, and population size. For auction houses the main parameters are slug which represents a short name for a realm and is useful for other api calls and connected_realms which contains the slug for all realms connected to the one represented by the JSON object. It also contains the slug for that realm.

import wowapi

api = wowapi.API('BattleNetAPIKey')
realm_status = api.realm_status()

auction_houses = []

for realm in realm_status['realms']:
    # I'm unsure what the internal-record objects are, but they are not valid
    # realms so they can be filtered out of the lists
    auction_house = filter(lambda x: "internal-record" not in x, realm['connected_realms'])
    auction_house.sort()
    if auction_house not in auction_houses:
      auction_houses.append(auction_house)

print("Number of unique auction houses: ", len(auction_houses)
for auction_house in auction_houses:
    print(auction_house)

This prints out a grand total of unique Auction Houses and a comma delimited list of the realms that make up each house.

Number of unique auction houses: 120
aegwynn, bonechewer, daggerspine, gurubashi, hakkar
aerie-peak
agamaggan, archimonde, burning-legion, jaedenar, the-underbog
aggramar, fizzcrank
...

Pulling a Snapshot

Snapshots are published to the API in two parts: an Auction House Status and the auction house data file (a link to which is provided in the status). For example api.auction_status("madoran") returns the following status for the Madoran realm (madoran is the slug for that realm):

{
  "files": [
    {
      "url": "http://us.battle.net/auction-data/52f853e2b29decd29e027d3a17fe1fba/auctions.json",
      "lastModified": 1438741937000
    }
  ]
}

While this data structure can support multiple files, I have yet to see an auction status that contains more than one file. Each snapshot is comprised of a url where the actual data can be downloaded from and a lastModified timestamp field that contains the milliseconds since Epoch. There is a helper function in wowapi.utility for downloading the additional file that takes in an auction status and returns a combined data structure with the auction status and an appended field data that holds the contents of the files in url.

import json
import wowapi
from wowapi.utility import retrieve_auctions

api = wowapi.API('BattleNetAPIKey')
auction_data = retrieve_auctions(api.auction_status("madoran"))
print(json.dumps(auction_data, indent=2, separators=(',', ': ')))

Which prints the following (the contents of auctions is explained in more detail in the following section):

{
  "files": [
    {
      "url": "http://us.battle.net/auction-data/52f853e2b29decd29e027d3a17fe1fba/auctions.json",
      "lastModified": 1438741937000,
      "data": {
        "realm": {
          "name": "Madoran",
          "slug": "madoran"
        },
        "auctions": {
          "auctions": [...]
        }
      }
    }
  ]
}

Auctions

Inside of a snapshot, the auctions field contains a list of individual auctions with a lot of data. Here is an example of one auction:

{
  "rand": 0,
  "auc": 841736577,
  "timeLeft": "VERY_LONG",
  "bid": 500000,
  "item": 109137,
  "seed": 0,
  "ownerRealm": "Dawnbringer",
  "context": 0,
  "owner": "CharacterName",
  "buyout": 600000,
  "quantity": 10
}

Auctions have a unique identifying number in the auc field. No information that I can find guarantees this is unique across Auction Houses or even within a single Auction House over time, but it does appear to be unique within a snapshot and for a single auction throughout its lifetime (if it appears in more than one snapshot).

The owner of the auction is identified by the owner and the ownerRealm fields. Because users in a connected realm set can share a username if they are on different realms, both fields are required to uniquely identify an auction owner.

The item(s) being sold in an auction is identified by the item, quantity, context, rand, and seed fields. The item field is the item id. Information about the actual item can be retrieved through another API call with api.item(itemID). The context provides information about the loot context for a item (what kind of dungeon it was looted from at what level) and was newly added in the 6.0.2 Update to the API. The rand field relates to the random enchantment that is applied to the item being sold . You can see a list of what the numbers mean on gamepedia. The quantity describes the number of items being sold in this auction.

The seed field is a tricky one because I’m not sure what it means. Looking around it seems to match the uniqueID from the in-game API’s item string. Some explanation on that can be found here. As far as I can tell it contains no useful information without access to internal Blizzard tools.

The “timeLeft” field appears to be intentionally vague. This can take one of four different string values indicating how long the auction will remain on the auction house before it expires:

SHORT - < 30 minutes left
MEDIUM - 30 minutes - 2 hours
LONG - 2 hours - 12 hours
VERY_LONG - 12 hours - 24 hours

The money related fields for an auction are bid and buyout. The numbers are given in copper (100 copper in 1 silver, 100 silver in 1 gold, 100 gold in the platinum I wish they would implement). When a user creates an auction they define a starting bid value and an optional buyout. If an auction has a buyout users can bypass the bid process and simply pay the buyout price. If the user doesn’t set a buyout price, the returned auction data has a buyout of 0.

< Billy Overton >