Coding Samples

There are many ways to use this library. Please be responsible and not be “that guy” who uses it as a jackhammer to pound the crap out of the API.

A primer on the API behavior

Let’s start with the basics. Search all players for me (Kamakazi Rusher)

>>> from wotconsole import WOTXSession as Session
>>> sess = Session() # We'll use the 'demo' API key for now
>>> kr = sess.player_search('Kamakazi Rusher')
>>> kr.data
[{u'nickname': u'Kamakazi Rusher', u'account_id': 2631240}]

Easy enough! You’ll notice that the JSON returned by the API is saved as the attribute WOTXResponse.data. For this method, it returns it as a nested dictionary within a list. This is because the API can return multiple items. If we instead search for all player names starting with “Kamakazi R”, we will get at least two players back.

>>> ks = sess.player_search('Kamakazi R')
>>> ks.data
[{u'nickname': u'Kamakazi Rebel', u'account_id': 4900488},
 {u'nickname': u'Kamakazi Rusher', u'account_id': 2631240}]

Not all methods will return lists. Some will return just nested dictionaries.

>>> t = sess.vehicle_info(tank_id=1, fields=['short_name', 'type'])
>>> t.data
{u'1': {u'type': u'mediumTank', u'short_name': u'T-34'}}

Be careful with methods that return dictionaries. You’ll notice that while we asked for a tank using an int, it returns it in the dictionary as a str instead

>>> t.data[1]  # KeyError will be thrown
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
KeyError: 1
>>> t.data['1'] # No errors!
{u'1': {u'type': u'mediumTank', u'short_name': u'T-34'}}

This is the default behavior of the API. I will not support automatic conversion of keys in the dictionaries!

If information for a player/tank/etc. is requested but does not exist in the database, it will be returned as a None value.

>>> p = sess.player_data(1)
>>> p.data
{u'1': None}

Exceeding parameter limits

Some methods have limitations on how many items you can request information for in one go. To accomodate for this, these methods will automagically split up the parameter into multiple requests and return them as one object.

For example, wotconsole.player_data has a max limit of 100 player IDs per request as per the API documentation. If you attempt to send more than 100 directly to the API, it will return an error code.

>>> import requests
>>> res = requests.get('https://api-xbox-console.worldoftanks.com/wotx/account/info/', params={
...   'application_id': 'demo',
...   'account_id': ','.join(map(str, range(5000,5101)))  # 101 IDs
... },
... timeout=10).json()
>>> res
{u'status': u'error', u'error': {u'field': u'account_id', u'message': u'ACCOUNT_ID_LIST_LIMIT_EXCEEDED', u'code': 407, . . . }

As of release v0.4, the library will auto-split parameters that have these limitations. For example,

>>> players = sess.player_data(range(5000, 5101), fields=['nickname'])
>>> players.meta
{u'count': 101}
>>> players.meta['count'] == len(players.data)
True