Using the TSM Web API to get Auction House pricing data!

What is an API?

An application programming interface or API is a set of clearly defined methods of communication between various software components. For TradeSkillMaster, these methods of communication allow an API user to query TSM for item pricing and other relevant information to use in their application(s) outside of the game.

What does the TSM Public Web API offer?

The kind of data you can query from the TSM Public Web API includes:

• Stats for a specific item
• Stats for every item for a specific region
• Stats for every item for a specific realm
• Item stats for a specific realm

Terminology

There is a baseline set of terminology which is important to understand when dealing with the public API:

• API Key - This is a unique, private key which is used to authenticate a TSM user with the authentication API. You can find your API key here. API keys should be handled with a similar level of security as you would handle a password and should never be made public
• Access Token - An access token is a short-lived key which is provided by the authentication API and is used to authenticate with other API endpoints. This token will either expire after a set amount of time or may be proactively revoked.
• Game Version - A version of the game (i.e. Retail or Wrath).
• Region - One of the supported areas of the world which data is provided for (i.e. US or EU). This maps to how Blizzard handles regions which means for example OCE is considered part of the US region.
• Realm - An in-game realm (i.e. Tichondrius). Note that Blizzard does not guarantee that realm names are unique for a given region / game version.
• Auction House - A unique in-game auction house. In classic, there is a single auction house per faction per group of connected realms. In retail, there is a single auction house per group of connected realms.

How do I query the TSM Public Web API?

All public API endpoints require an access token which can be generated by providing your personal TSM API key to the auth API. You can view your API key at https://id.tradeskillmaster.com/realms/app/account Note that you should keep this API key private and not share it with anybody.

To generate an access token, you send a POST request to https://auth.tradeskillmaster.com/oauth2/token with the following content:

{

    "client_id": "c260f00d-1071-409a-992f-dda2e5498536",

    "grant_type": "api_token",

    "scope": "app:realm-api app:pricing-api",

    "token": "<YOUR_API_KEY>"

}

Here is an example request and response:

The auth API returns a few things, but for now, we'll just take note of the access_token, as this is what we need to pass to other API endpoints. The other values can be ignored for most simple use-cases.

Realm API

The realm API provides information on the regions, realms, and auction houses which TSM provides data for. The full documentation for the available public realm APIs can be found here.

Let's walk through an example to look up the auction house ID for Retail US-Tichondrius. First, we can list all the available regions and see that the regionId for US ("North America") is 1:

We can then list all the available realms within that region and find that the auction house ID we're after is 4:

Pricing API

The pricing API provides TSM AuctionDB pricing data at both a region and auction house level. The full documentation for the available public pricing APIs can be found here.

Let's walk through an example to look up the price of Ghost Iron Ore on Retail US-Tichondrius. From above, we know that the auction house ID we care about is 4 and the itemID of the item we want is 72092, so we can fetch its AuctionDB data as follows:

Let's also look up the region data for that same item:

If instead we want to get data for all items TSM has seen on an auction house, we can request stats for every item:

Please note that this is an expensive request and can take a while to complete.

Rate Limits

Some API endpoints have limits enforced on how often they may be called. If you exceed these limits, you will get a 429 response code from the API until the specified period of time has elapsed. The limits are currently as follows:

• Pricing API:

• /region/{regionId}/item/{itemId} - 500 per 24 hours

• /ah/{auctionHouseId}/item/{itemId} - 500 per 24 hours

• /region/{regionId} - 10 per 24 hours

• /ah/{auctionHouseId} - 100 per 24 hours

We reserve the right to change these limits at any time and/or revoke access to the public API for any application or user who is found to be abusing the API or causing excessive load on our servers, regardless of whether or not they hit the published limits.

Google Sheets Example

We provide an example Google Sheet and associated Google App Script which pulls all item stats for a specified retail WoW region and realm here. If you’re looking to build on top of this, you should make a copy of it and edit the functions at the bottom of the associated Google App Script to fit the Google Sheet you’re looking to build.

Advanced Integrations

If you have a use-case in mind which involves data which we don't currently make public via the API, requires a different authentication strategy (i.e. where end-users aren't directly entering their API key), requires higher rate limits, or otherwise doesn't align well with the current stated goals or implementation of the public API, feel free to contact us at [email protected] with more details on your use-case!

Questions / Support

If you have any questions or run into any issues with the public API, join us in Discord.