Explaining World of Warcraft Auction Snapshots
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.
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
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.
This prints out a grand total of unique Auction Houses and a comma delimited list of the realms that make up each house.
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):
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
Which prints the following (the contents of
auctions is explained in more
detail in the following section):
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:
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
The owner of the auction is identified by the
owner and the
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
seed fields. The
item field is the item id.
Information about the actual item can be retrieved through another API call with
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.
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
quantity describes the number of
items being sold in this auction.
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
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
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.