Skip to main content

Travian: Kingdom utilities for your need.

Project description


Travian: Kingdom utilities for your need.
It provide several object that mostly used on Travian: Kingdom such as Map, Villages, Notepad, and Farmlist.

PyPI version Python 3.6 Build Status codecov Code style: black License: MIT

Table of Contents


It is recommended to use virtualenv or any other similar virtual environment management for python.

Since tkpy depend on primordial package, first you need to install primordial package.

pip install git+

Getting started

tkpy need Gameworld object from primordial package so it can request data from Travian: Kingdom. Use authenticate function to retrieve Gameworld object.

from tkpy import authenticate

driver = authenticate(email='', password='your password', gameworld='com12')



Map object is an object for keeping map data from Travian: Kingdom.
To get map data from Travian: Kingdom, you need to call pull method.

from tkpy import Map

m = Map(driver)

Once you call pull method, now you can get all tiles data using several method.

all_villages = list(m.gen_villages()) # get all villages from map
abandoned_valleys = list(m.gen_abandoned_valley()) # get all unsettled tiles from map
oases = list(m.gen_oases()) # get all oases from map
grey_villages = list(m.gen_grey_villages()) # get all grey villages from map

Or if you want to get data from specific tile, you can use coordinate method.

m.coordinate(0, 0)
<Cell({'id': '536887296', 'landscape': '9013', 'owner': '0'})>

When you call pull method, you also will get player data and kingdom data. Map object will keep this data and you can get player data or kingdom data using several method.

player_list = list(m.gen_players()) # get all players
kingdom_list = list(m.gen_kingdoms()) # get all kingdoms
inactive_player_list = list(m.gen_inactive_players()) # get all inactive players

If you want to get data from specific player or kingdom, you can use get_player method and get_kingdom method.

m.get_player('player name')
<Player({'name': 'player name', 'country': 'en', 'tribeId': '1', ...})>

m.get_kingdom('kingdom name')
<Kingdom({'tag': 'kingdom name', 'kingdomId': '9999'})>

If you want to slice map data based on the area of your interest, you can use slice_map method.

sliced_map = m.slice_map(center=(0, 0), radius=5)

# now you can do the same thing as `Map` object
grey_villages = list(sliced_map.gen_grey_villages())


Villages object is like built-in dict object from Python so you can access the village using its name as key. To get village data from Travian: Kingdom, you need to call pull method first.

from tkpy import Villages

v = Villages(driver)

v['your first village']
<Village({'villageId': '537313245', 'playerId': '001', 'name': 'my first village',...})>

From Villages object you can get Village object and from this object you can do send_attack, send_raid, send_defend, send_spy, and send_siege.

If you want to attack, you need to get troop enum from tkpy.

from tkpy import RomanTroop # if you are a Roman tribe

first_village = v['your first village'] # get your first village object
units_siege = {RomanTroop.IMPERIAN: 1000, RomanTroop.BATTERING_RAM: 1} # prepare unit
units_attack = {RomanTroop.LEGIONNAIRE: 1000} # prepare unit
units_raid = {RomanTroop.EQUITES_IMPERATORIS: 50} # prepare unit
units_defend = {RomanTroop.PRAETORIAN: 1000} # prepare unit

first_village.send_siege(x=0, y=0, units=units_siege) # send siege
first_village.send_attack(x=0, y=0, units=units_attack) # send attack
first_village.send_raid(x=0, y=0, units=units_raid) # send raid
first_village.send_spy(x=0, y=0, amount=1) # send spy
first_village.send_defend(x=0, y=0, untis=unts_defend) # send defend

From Village object you can also upgrade building that on the village by using upgrade method. And if you want to construct building, you can use construct method.

If you want to upgrade or construct building, you need to get building enum from tkpy.

from tkpy import BuildingType

first_village = v['your first village'] # get your first village object
first_village.upgrade(building=BuildingType.MAIN_BUILDING) # upgrade main building
first_village.construct(buildng=BuildingType.WAREHOUSE) # construct warehouse


Farmlist object is like built-in dict object from Python so you can access farmlist using its name as key. To get farmlist data from Travian: Kingdom, you need to call pull method first. From Farmlist you can create new farmlist by calling create_farmlist.

from tkpy import Farmlist

f = Farmlist(driver)

f['Startup farm list']
<FarmlistEntry({'listId': '1631', 'listName': 'Startup farm list', ...})>

f.create_farmlist('new farmlist')
f['new farmlist']
<FarmlistEntry({'listId': '1632', 'listName': 'new farmlist', ...})>

From Farmlist object you can get FarmlistEntry object and from it you can add new village to the FarmlistEntry and send this FarmlistEntry.

f['Startup farm list'].add(villageId=536887296) # add village using village id to 'Startup farm list'
f['Startup farm list'].send(villageId=537051141) # send 'startup farm list' from village using village id


Notepad is an object that when instantiate will create new notepad in game. Use message method for write new message.

from tkpy import Notepad

n = Notepad(driver) # new notepad will appear in game
n.message('this is new message on new notepad') # write message to the notepad

# careful, use `message` method will overwrite message previously on notepad
n.message('old message will be overwrited')


For documentation, you can go to this wiki.


Please note that this is a research project, i am by no means responsible for any usage of this utilities.
Use on your own behalf, i am also not responsible if your accounts get banned due to extensive use of this utilites.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for tkpy, version 0.0.1b4
Filename, size File type Python version Upload date Hashes
Filename, size tkpy-0.0.1b4-py3-none-any.whl (24.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size tkpy-0.0.1b4.tar.gz (23.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page