get-wow-data-async

get-wow-data-async implements asynchronous requests to the World of Warcraft (WoW) APIs so you don’t have to.

Example: Get the value of all auctions from the Winterhoof server.

import getwowdataasync
import asyncio

async def main():
    us_api = await getwowdataasync.WowApi.create('us') #region
    winterhoof_auctions = await us_api.get_auctions(4) #4 = Winterhoof's connected realm id
    await us_api.close() #close aiohttp session after queries are done

    total_value = 0
    for item in winterhoof_auctions['auctions']:
        if item.get('unit_price'):
            total_value += item.get('unit_price')
        elif item.get('buyout'):
            total_value += item.get('buyout')
        elif item.get('bid'):
            total_value += item.get('bid')

    print(getwowdataasync.as_gold(total_value))
    #prints 430,846,968g 67s 00c

asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy()) #if relevent
asyncio.run(main())

Features

Much faster then my other synchronous get-wow-data package. Supported APIs. (see this for a complete list of APIs provided by blizzard. Not all are consumeable, currently, by get-wow-data-async)

  • Connected Realms

  • Items

    • Icons

  • Auctions

  • Professions

    • Recipes

    • Icons

  • Wow Token

Installing

get-wow-data-async is avilable on PyPi:

$ python -m pip install getwowdataasync

Setup

To access any blizzard API you need a Client Id and Client Secret.

  1. Go to https://develop.battle.net/

  2. Click on Get started and login.

  3. Now click create client and fill out the form.

  4. You now have a Client Id and Client Secret to query Blizzards APIs

Remember not to commit your wow_api_secret! Set wow_api_id and wow_api_secret as environment variables and get-wow-data-async will read these credentials from there.

Setting the client id and secret as an environment variable

dotenv is used inside WowApi.create() to get your client id and secret.

  1. Create a file called .env

  2. Set wow_api_id andwow_api_secret

wow_api_id = x
wow_api_secret = y

Now WowApi.create() will use those variabels to get an access token for future requests.

API

There are two ways to consume the World of Warcraft APIs search or get methods. Both types of methods require similar data like an access token, region, … the WowApi class contains that data.

Get

Most WoW APIs don’t have search functionality provided by blizzard. This means the requests you make to them are restricted to specific fields usually an id.

from pprint import pprint
from getwowdataasync import WowApi

async def main():
    us_api = await WowApi.create('us')
    wow_token_data = await us_api.get_wow_token()
    await us_api.close()

    pprint(wow_token_data)
    #prints:
    # {'_links': {'self': {'href': 'https://us.api.blizzard.com/data/wow/token/?namespace=dynamic-us'}},
    # 'last_updated_timestamp': 1653847530000,
    # 'price': 1656890000}
class getwowdataasync.getdata.WowApi

Instantiate with WowApi.create(‘region’). You need to have your blizzard api client credentials inside a .env or passed in. Then use its methods to query the API.

async close()

Closes aiohttp.ClientSession.

Preforms a search of all realms in that region.

Parameters:

filters (dict) – Parameters for refining a search request. See https://develop.battle.net/documentation/world-of-warcraft/guides/search

Returns:

The search results as json parsed into a dict.

async classmethod create(region: str, locale: str = 'en_US', wow_api_id: Optional[str] = None, wow_api_secret: Optional[str] = None)

Gets an instance of WowApi with an access token, region, and httpx client.

Parameters:

  • region (str) – Each region has its own data. This specifies which regions data WoWApi will consume.

  • locale (str) – The language some elements will return. Realms, for example, can return their names in a single language or all supported ones.

  • wow_api_id (str) – Your api client id from blizzards api website

  • wow_api_secret (str) – Your api client secret from blizzards api website

Returns:

An instance of the WowApi class.

async get_all_items() → list

Adds all urls from an item or realm search to the queue.

A worker is then needed to remove urls from the queue and make requests with them.

async get_all_realms() → list

Returns all realms in WowApi’s given region.

async get_auctions(connected_realm_id) → dict

Returns the all auctions in a connected realm by their connected realm id.

Parameters:

connected_realm_id (int) – The id of a connected realm cluster.

async get_commodities() → dict

Returns all commodities data for the region.

async get_connected_realm_index() → dict

Returns a dict of all realm’s names with their connected realm id.

async get_connected_realms_by_id(connected_realm_id: int) → dict

Returns the all realms in a connected realm by their connected realm id.

Parameters:

connected_realm_id (int) – The id of a connected realm cluster.

async get_item_classes() → dict

Returns all item classes (consumable, container, weapon, …).

async get_item_icon(item_id: int) → dict

Returns a dict with a link to an item’s icon.

Parameters:

item_id (int) – The items id. Get from item_search().

async get_item_set_index() → dict

Returns all item sets. Ex: teir sets

async get_item_subclasses(item_class_id: int) → dict

Returns all item subclasses (class: consumable, subclass: potion, elixir, …).

Parameters:

item_class_id (int) – Item class id. Found with get_item_classes().

async get_items_by_expansion(expansion_name: str) → list

Gets all items from an expansion.

Currently only Dragonflight is supported. To extend find the first and last item id’s of each expansion.

Parameters:

expansion_name (str) – Name of a WoW expansion. Ex: “Classic”, “Burning Crusade”, “Dragonflight”

Returns:

A list containing all the items from the specified expansion.

async get_profession_icon(profession_id: int) → dict

Returns json with a link to a professions icon.

Parameters:

profession_id (int) – The id of a profession. Get from get_profession_index.

async get_profession_index(true_professions_only: bool = True) → dict

Returns the all professions.

Parameters:

true_professions_only (bool) – When true (defualt) this only returns primary and secondary professions like jewelcrafting, leatherworking, … not strange ones like protoform synthesis or archaeology (rip).

async get_profession_tiers(profession_id: int) → dict

Returns the all profession skill tiers in a profession by their profession id.

A profession teir includes all the recipes from that expansion. Teir examples are classic, tbc, shadowlands, …

Parameters:

profession_id (int) – The id of a profession. Get from get_profession_index().

async get_professions_tree_by_expansion(expansion_name: str) → list

Returns all professions and recipes from a provided expaneion.

Parameters:

Expansion_name (str) – The initals of an expansion. Currently only ‘df’ for Dragonflight is currently supported.

Returns:

A list of profession dictionaries with all of that profession’s recipes divided by caregory (‘Shields, Armor, …’)

async get_recipe(recipe_id: int) → dict

Returns a recipe by its id.

Parameters:

recipe_id (int) – The id from a recipe. Found in get_profession_tier_details().

async get_recipe_categories(profession_id: int, skill_tier_id: int) → dict

Returns all crafts from a skill teir.

Included in this response are the categories like belts, capes, … and the item within them. This is broken down by skill tier (tbc, draenor, shadowlands).

Parameters:

  • profession_id (int) – The profession’s id. Found in get_profession_index().

  • skill_tier_id (int) – The skill teir id. Found in get_profession_teirs().

async get_recipe_icon(recipe_id: int) → dict

Returns a dict with a link to a recipes icon.

Parameters:

recipe_id (int) – The id from a recipe. Found in get_profession_tier_details().

async get_wow_token() → dict

Returns data on the regions wow token such as price.

Preforms a search across all items.

Parameters:

extra_params (dict) – Parameters for refining a search request. See https://develop.battle.net/documentation/world-of-warcraft/guides/search

Returns:

The search results as json parsed into a dict.

getwowdataasync.getdata.as_gold(amount: int) → str

Formats a integer as n*g nns nnc where n is some number, g = gold, s = silver, and c = copper.

Parameters:

amount (int) – The value of something in WoW’s currency.

Returns:

A string formatted to WoW’s gold, silver, copper currency.

getwowdataasync.getdata.convert_to_datetime(Date: str)

Takes last-modified header and converts it to a datetime object.

getwowdataasync.getdata.get_id_from_url(url: str) → int

Returns the id from a url.

This matches to the first number in a string. As of writing the only number in blizzard’s urls is an id.

Parameters:

url (str) – The url that contains a single number id.

Returns:

The number found in the url.

getwowdataasync.getdata.load_dotenv(dotenv_path: Optional[Union[str, PathLike]] = None, stream: Optional[IO[str]] = None, verbose: bool = False, override: bool = False, interpolate: bool = True, encoding: Optional[str] = 'utf-8') → bool

Parse a .env file and then load all the variables found as environment variables.

  • dotenv_path: absolute or relative path to .env file.

  • stream: Text stream (such as io.StringIO) with .env content, used if dotenv_path is None.

  • verbose: whether to output a warning the .env file is missing. Defaults to False.

  • override: whether to override the system environment variables with the variables in .env file. Defaults to False.

  • encoding: encoding to be used to read the file.

If both dotenv_path and stream, find_dotenv() is used to find the .env file.

getwowdataasync.getdata.urljoin(base, url, allow_fragments=True)

Join a base URL and a possibly relative URL to form an absolute interpretation of the latter.

Notes on the data

Visit https://develop.battle.net/documentation/world-of-warcraft for blizzard official documentation.

Below are notes that i’ve gathered from the documentation, reading the returned data, and from forum posts/reddit.

Reading json

Using a normal print() on response.json() outputs gibberish. I recommend either the pprint module or viewing the json from this list of all the available APIs.

Href’s

The href’s in the json are links to related elements. One of the links will be to the url that produced that data.

Prices

The prices or value of an item is in the following format g*sscc, where g = gold, s = silver, c = copper. Silver and copper are fixed in the last 4 decimal spaces whlie gold can be as any number of spaces before silver. So 25289400 is 2528g 94s 00c.

buyout vs unit_price

Stackable items have a single unit_price while unique items like weapons have a bid/buyout price.

Item bonus list

The item bonus list are the modifiers applied to an item, such as the level its scaled to. Blizzard does not make the bonus values and their corresponding effects available through an API. (Boo)

Versions of an item with different bonuses can be found on wowhead. Mouse over select version and pick your desired version from the drop down menu.

Item context

Where the item was created. Incomplete list

Context

Value

1

Normal Dungeon

5

Heroic Raid

11

Quest Reward

14

Vendor

15

Black Market

Item modifiers

No idea

Parameter Cheatsheet

Incomplete list

Region

Namespace

locale (language)

us

static-{region}

en_US

eu

dynamic-{region}

es_MX

kr

profile-{region}

pt_BR

tw

de_DE

cn

en_GB

es_ES

fr_FR

it_IT

ru_RU

ko_KR

zh_TW

zh_CN

Feedback

Feel free to file an issue.

I’m currently teaching myself how to code, so, if you have any suggestions or corrections I would really appriciate it!

License

MIT