API Reference

This module implements a variety of classes used to hold the data parsed from Tibia.com.

These objects are generally obtained from their respective from_content methods. It is possible to create and edit these objects as desired, but it may lead to unexpected behaviour if not done properly.

Client

class tibiapy.Client(loop=None, session=None)[source]

An asynchronous client that fetches information from Tibia.com.ArithmeticError

The client uses a aiohttp.ClientSession to request the information. A single session is shared across all operations.

If desired, a custom ClientSession instance may be passed, instead of creating a new one.

New in version 2.0.0.

loop

asyncio.AbstractEventLoop – The event loop to use. The default one will be used if not defined.

session

aiohttp.ClientSession – The client session that will be used for the requests. One will be created by default.

coroutine fetch_character(name)[source]

Fetches a character by its name from Tibia.com

Parameters:

name (str) – The name of the character.
Returns:

The character if found, else None.
Return type:

Character
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_guild(name)[source]

Fetches a guild by its name from Tibia.com

Parameters:

name (str) – The name of the guild. The case must match exactly.
Returns:

The guild if found, else None.
Return type:

Guild
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_highscores_page(world, category=Category.EXPERIENCE, vocation=<VocationFilter.ALL: 0>, page=1)[source]

Fetches a single highscores page from Tibia.com

Parameters:
  • world (str) – The world to search the highscores in.
  • category (Category) – The highscores category to search, by default Experience.
  • vocation (VocationFilter) – The vocation filter to use. No filter used by default.
  • page (int) – The page to fetch, by default the first page is fetched.
Returns:

The highscores information or None if not found.
Return type:

Highscores
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_house(house_id, world)[source]

Fetches a house in a specific world by its id.

Parameters:
  • house_id (int) – The house’s internal id.
  • world (str) – The name of the world to look for.
Returns:

The house if found, None otherwise.
Return type:

House
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_kill_statistics(world)[source]

Fetches the kill statistics of a world from Tibia.com.

Parameters:

world (str) – The name of the world.
Returns:

The kill statistics of the world if found.
Return type:

KillStatistics
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_news(news_id)[source]

Fetches a news entry by its id from Tibia.com

Parameters:

news_id (int) – The id of the news entry.
Returns:

The news entry if found, None otherwise.
Return type:

News
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_news_archive(begin_date, end_date, categories=None, types=None)[source]

Fetches news from the archive meeting the search criteria.

Parameters:
  • begin_date (datetime.date) – The beginning date to search dates in.
  • end_date (datetime.date) – The end date to search dates in.
  • categories (list of NewsCategory) – The allowed categories to show. If left blank, all categories will be searched.
  • types (list of ListedNews) – The allowed news types to show. if unused, all types will be searched.
Returns:

The news meeting the search criteria.
Return type:

list of ListedNews
Raises:
  • ValueError: – If begin_date is more recent than end_date.
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_recent_news(days=30, categories=None, types=None)[source]

Fetches all the published news in the last specified days.

This is a shortcut for fetch_news_archive(), to handle dates more easily.

Parameters:
  • days (int) – The number of days to search, by default 30.
  • categories (list of NewsCategory) – The allowed categories to show. If left blank, all categories will be searched.
  • types (list of ListedNews) – The allowed news types to show. if unused, all types will be searched.
Returns:

The news posted in the last specified days.
Return type:

list of ListedNews
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_world(name)[source]

Fetches a world from Tibia.com

Parameters:

name (str) – The name of the world.
Returns:

The world’s information if found, `None otherwise.
Return type:

World
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_world_guilds(world: str)[source]

Fetches the list of guilds in a world from Tibia.com

Parameters:

world (str) – The name of the world.
Returns:

The lists of guilds in the world.
Return type:

list of ListedGuild
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_world_houses(world, town, house_type=HouseType.HOUSE)[source]

Fetches the house list of a world and type.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – The type of building. House by default.
Returns:

The lists of houses meeting the criteria if found.
Return type:

list of ListedHouse
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.
coroutine fetch_world_list()[source]

Fetches the world overview information from Tibia.com.

Returns:

The world overview information.
Return type:

WorldOverview
Raises:
  • Forbidden – If a 403 Forbidden error was returned. This usually means that Tibia.com is rate-limiting the client because of too many requests.
  • NetworkError – If there’s any connection errors during the request.

Enumerations

Enumerations are provided for various values in order to avoid depending on strings.

class tibiapy.HouseType[source]

The types of house available.

HOUSE = 'house'
GUILDHALL = 'guildhall'
class tibiapy.AccountStatus[source]

Possible account statuses.

FREE_ACCOUNT = 'Free Account'
PREMIUM_ACCOUNT = 'Premium Account'
class tibiapy.Category[source]

The different highscores categories.

ACHIEVEMENTS = 'achievements'
AXE_FIGHTING = 'axe'
CLUB_FIGHTING = 'club'
DISTANCE_FIGHTING = 'distance'
EXPERIENCE = 'experience'
FISHING = 'fishing'
FIST_FIGHTING = 'fist'
LOYALTY_POINTS = 'loyalty'
MAGIC_LEVEL = 'magic'
SHIELDING = 'shielding'
SWORD_FIGHTING = 'sword'
class tibiapy.HouseStatus[source]

Renting statuses of a house.

RENTED = 'rented'
AUCTIONED = 'auctioned'
class tibiapy.NewsCategory[source]

The different news categories.

CIPSOFT = 'cipsoft'
COMMUNITY = 'community'
DEVELOPMENT = 'development'
SUPPORT = 'support'
TECHNICAL_ISSUES = 'technical'
class tibiapy.NewsType[source]

The different types of new entries.

NEWS_TICKER = 'News Ticker'
FEATURED_ARTICLE = 'Featured Article'
NEWS = 'News'
class tibiapy.PvpType[source]

The possible PvP types a World can have.

OPEN_PVP = 'Open PvP'
OPTIONAL_PVP = 'Optional PvP'
RETRO_OPEN_PVP = 'Retro Open PvP'
RETRO_HARDCORE_PVP = 'Retro Hardcore PvP'
HARDCORE_PVP = 'Hardcore PvP'
class tibiapy.Sex[source]

Possible character sexes.

MALE = 'male'
FEMALE = 'female'
class tibiapy.TransferType[source]

The possible special transfer restrictions a world may have.

REGULAR = 'regular'

No special transfer restrictions

BLOCKED = 'blocked'

Can’t transfer to this world, but can transfer out of this world.

LOCKED = 'locked'

Can transfer to this world, but can’t transfer out of this world.

class tibiapy.Vocation[source]

The possible vocation types.

NONE = 'None'
DRUID = 'Druid'
KNIGHT = 'Knight'
PALADIN = 'Paladin'
SORCERER = 'Sorcerer'
ELDER_DRUID = 'Elder Druid'
ELITE_KNIGHT = 'Elite Knight'
ROYAL_PALADIN = 'Royal Paladin'
MASTER_SORCERER = 'Master Sorcerer'
class tibiapy.VocationFilter[source]

The vocation filters available for Highscores.

classmethod from_name(name, all_fallback=True)[source]

Gets a vocation filter from a vocation’s name.

Parameters:
  • name (str) – The name of the vocation.
  • all_fallback (bool) – Whether to return ALL if no match is found. Otherwise, None will be returned.
Returns:

The matching vocation filter.
Return type:

VocationFilter, optional
ALL = 0
KNIGHTS = 1
PALADINS = 2
SORCERERS = 3
DRUIDS = 4
class tibiapy.WorldLocation[source]

The possible physical locations for servers.

EUROPE = 'Europe'
NORTH_AMERICA = 'North America'
SOUTH_AMERICA = 'South America'

Main Models

The following models all contain their respective from_content methods. They all have their respective section in Tibia.com

Character

class tibiapy.Character(name=None, world=None, vocation=None, level=0, sex=None, **kwargs)[source]

Represents a Tibia character.

name

str – The name of the character.

deletion_date

datetime.datetime, optional – The date when the character will be deleted if it is scheduled for deletion.

former_names

list of str – Previous names of the character.

sex

Sex – The character’s sex.

vocation

Vocation – The character’s vocation.

level

int – The character’s level.

achievement_points

int – The total of achievement points the character has.

world

str – The character’s current world.

former_world

str, optional – The previous world the character was in, in the last 6 months.

residence

str – The current hometown of the character.

married_to

str, optional – The name of the character’s spouse.

house

CharacterHouse, optional – The house currently owned by the character.

guild_membership

GuildMembership, optional – The guild the character is a member of.

last_login

datetime.datetime, optional – The last time the character logged in. It will be None if the character has never logged in.

position

str, optional – The position of the character (e.g. CipSoft Member), if any.

comment

str, optional – The displayed comment.

account_status

AccountStatus – Whether the character’s account is Premium or Free.

achievements

list of Achievement – The achievements chosen to be displayed.

deaths

list of Death – The character’s recent deaths.

account_information

AccountInformation, optional – The character’s account information, if visible.

other_characters

list of OtherCharacter – Other characters in the same account. It will be empty if the character is hidden, otherwise, it will contain at least the character itself.

deleted

bool – Whether the character is scheduled for deletion or not.

guild_name

str – The name of the guild the character belongs to, or None.

guild_rank

str – The character’s rank in the guild they belong to, or None.

guild_url

str – The character’s rank in the guild they belong to, or None.

hidden

bool – Whether this is a hidden character or not.

married_to_url

str – The URL to the husband/spouse information page on Tibia.com, if applicable.

classmethod from_content(content)[source]

Creates an instance of the class from the html content of the character’s page.

Parameters:content (str) – The HTML content of the page.
Returns:The character contained in the page, or None if the character doesn’t exist
Return type:Character
Raises:InvalidContent – If content is not the HTML of a character’s page.
classmethod from_tibiadata(content)[source]

Builds a character object from a TibiaData character response.

Parameters:content (str) – The JSON content of the response.
Returns:The character contained in the page, or None if the character doesn’t exist
Return type:Character
Raises:InvalidContent – If content is not a JSON string of the Character response.
classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

Guild

class tibiapy.Guild(name=None, world=None, **kwargs)[source]

Represents a Tibia guild.

name

str – The name of the guild.

logo_url

str – The URL to the guild’s logo.

description

str, optional – The description of the guild.

world

str – The world this guild belongs to.

founded

datetime.date – The day the guild was founded.

active

bool – Whether the guild is active or still in formation.

guildhall

GuildHouse, optional – The guild’s guildhall if any.

open_applications

bool – Whether applications are open or not.

disband_date

datetime.datetime, optional – The date when the guild will be disbanded if the condition hasn’t been meet.

disband_condition

str, optional – The reason why the guild will get disbanded.

homepage

str, optional – The guild’s homepage, if any.

members

list of GuildMember – List of guild members.

invites

list of GuildInvite – List of invited characters.

member_count

int – The number of members in the guild.

online_count

int – The number of online members in the guild.

online_members

list of GuildMember – List of currently online members.

ranks

list of str – Ranks in their hierarchical order.

classmethod from_content(content)[source]

Creates an instance of the class from the HTML content of the guild’s page.

Parameters:content (str) – The HTML content of the page.
Returns:The guild contained in the page or None if it doesn’t exist.
Return type:Guild
Raises:InvalidContent – If content is not the HTML of a guild’s page.
classmethod from_tibiadata(content)[source]

Builds a guild object from a TibiaData character response.

Parameters:content (str) – The json string from the TibiaData response.
Returns:The guild contained in the description or None.
Return type:Guild
Raises:InvalidContent – If content is not a JSON response of a guild’s page.
classmethod get_url(name)

Gets the Tibia.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page on TibiaData.com.
Return type:str
classmethod get_world_list_url(world)

Gets the Tibia.com URL for the guild section of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page
Return type:str
classmethod get_world_list_url_tibiadata(world)

Gets the TibiaData.com URL for the guild list of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the guild’s information page on Tibia.com.

url_tibiadata

str – The URL to the guild on TibiaData.com.

Highscores

class tibiapy.Highscores(world, category, **kwargs)[source]

Represents the highscores of a world.

Tibia.com only shows 25 entries per page. TibiaData.com shows all results at once.

New in version 1.1.0.

world

str – The world the highscores belong to.

category

Category – The selected category to displays the highscores of.

vocation

VocationFilter – The selected vocation to filter out values.

entries

list of HighscoresEntry – The highscores entries found.

results_count

int – The total amount of highscores entries in this category. These may be shown in another page.

from_rank

int – The starting rank of the provided entries.

to_rank

int – The last rank of the provided entries.

page

int – The page number the shown results correspond to on Tibia.com

total_pages

int – The total of pages of the highscores category.

url

str – The URL to the highscores page on Tibia.com containing the results.

url_tibiadata

str – The URL to the highscores page on TibiaData.com containing the results.

classmethod from_content(content)[source]

Creates an instance of the class from the html content of a highscores page.

Notes

Tibia.com only shows up to 25 entries per page, so in order to obtain the full highscores, all 12 pages must be parsed and merged into one.

Parameters:content (str) – The HTML content of the page.
Returns:The highscores results contained in the page.
Return type:Highscores
Raises:InvalidContent – If content is not the HTML of a highscore’s page.
classmethod from_tibiadata(content, vocation=None)[source]

Builds a highscores object from a TibiaData highscores response.

Notes

Since TibiaData.com’s response doesn’t contain any indication of the vocation filter applied, vocation can’t be determined from the response, so the attribute must be assigned manually.

If the attribute is known, it can be passed for it to be assigned in this method.

Parameters:
  • content (str) – The JSON content of the response.
  • vocation (VocationFilter, optional) – The vocation filter to assign to the results. Note that this won’t affect the parsing.
Returns:

The highscores contained in the page, or None if the content is for the highscores of a nonexistent world.
Return type:

Highscores
Raises:

InvalidContent – If content is not a JSON string of the highscores response.
classmethod get_url(world, category=Category.EXPERIENCE, vocation=<VocationFilter.ALL: 0>, page=1)[source]

Gets the Tibia.com URL of the highscores for the given parameters.

Parameters:
  • world (str) – The game world of the desired highscores.
  • category (Category) – The desired highscores category.
  • vocation (VocationFiler) – The vocation filter to apply. By default all vocations will be shown.
  • page (int) – The page of highscores to show.
Returns:
Return type:

The URL to the Tibia.com highscores.
classmethod get_url_tibiadata(world, category=Category.EXPERIENCE, vocation=<VocationFilter.ALL: 0>)[source]

Gets the TibiaData.com URL of the highscores for the given parameters.

Parameters:
  • world (str) – The game world of the desired highscores.
  • category (Category) – The desired highscores category.
  • vocation (VocationFiler) – The vocation filter to apply. By default all vocations will be shown.
Returns:
Return type:

The URL to the TibiaData.com highscores.
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

House

class tibiapy.House(name, world=None, **kwargs)[source]

Represents a house in a specific world.

id

int – The internal ID of the house. This is used on the website to identify houses.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

image_url

str – The URL to the house’s minimap image.

beds

int – The number of beds the house has.

size

int – The number of SQM the house has.

rent

int – The monthly cost paid for the house, in gold coins.

owner

str – The current owner of the house, if any.

owner_sex

Sex – The sex of the owner of the house, if applicable.

paid_until

datetime.datetime, optional – The date the last paid rent is due.

transfer_date

datetime.datetime, optional – The date when the owner will move out of the house, if applicable.

transferee

str, optional – The character who will receive the house when the owner moves, if applicable.

transfer_price

int – The price that will be paid from the transferee to the owner for the house transfer.

transfer_accepted

bool – Whether the house transfer has already been accepted or not.

highest_bid

int – The currently highest bid on the house if it is being auctioned.

highest_bidder

str, optional – The character that holds the highest bid.

auction_end

datetime.datetime, optional – The date when the auction will end.

owner_url

str – The URL to the Tibia.com page of the house’s owner, if applicable.

transferee_url

str – The URL to the Tibia.com page of the character receiving the house, if applicable.

highest_bidder_url

str – The URL to the Tibia.com page of the character with the highest bid, if applicable.

classmethod from_content(content)[source]

Parses a Tibia.com response into a House object.

Parameters:content (str) – HTML content of the page.
Returns:The house contained in the page, or None if the house doesn’t exist.
Return type:House
Raises:InvalidContent – If the content is not the house section on Tibia.com
classmethod from_tibiadata(content)[source]

Parses a TibiaData response into a House object.

Parameters:content (str) – The JSON content of the TibiaData response.
Returns:The house contained in the response, if found.
Return type:House
Raises:InvalidContent – If the content is not a house JSON response from TibiaData
classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_url(house_id, world)

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the Tibia.com page of the house.

url_tibiadata

str – The URL to the TibiaData.com page of the house.

KillStatistics

class tibiapy.KillStatistics(world, entries=None, total=None)[source]

Represents the kill statistics of a world.

world

str – The world the statistics belong to.

entries

dict – A dictionary of kills entries of every race, where the key is the name of the race.

total

RaceEntry – The kill statistics totals.

url

str – The URL to the kill statistics page on Tibia.com containing the results.

players

RaceEntry – The kill statistics for players.

classmethod get_url(world)[source]

Gets the Tibia.com URL of the kill statistics of a world.

Parameters:world (str) – The game world of the desired kill statistics.
Returns:
Return type:The URL to the Tibia.com kill statistics for this world.
classmethod from_content(content)[source]

Creates an instance of the class from the HTML content of the kill statistics’ page.

Parameters:content (str) – The HTML content of the page.
Returns:The kill statistics contained in the page or None if it doesn’t exist.
Return type:KillStatistics
Raises:InvalidContent – If content is not the HTML of a kill statistics’ page.
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

ListedGuild

class tibiapy.ListedGuild(name, world, logo_url=None, description=None, active=False)[source]

Represents a Tibia guild in the guild list of a world.

name

str – The name of the guild.

logo_url

str – The URL to the guild’s logo.

description

str, optional – The description of the guild.

world

str – The world this guild belongs to.

active

bool – Whether the guild is active or still in formation.

classmethod list_from_content(content)[source]

Gets a list of guilds from the HTML content of the world guilds’ page.

Parameters:content (str) – The HTML content of the page.
Returns:List of guilds in the current world. None if it’s the list of a world that doesn’t exist.
Return type:list of ListedGuild
Raises:InvalidContent – If content is not the HTML of a guild’s page.
classmethod list_from_tibiadata(content)[source]

Builds a character object from a TibiaData character response.

Parameters:content (str) – A string containing the JSON response from TibiaData.
Returns:The list of guilds contained.
Return type:list of ListedGuild
Raises:InvalidContent – If content is not a JSON response of TibiaData’s guild list.
classmethod get_url(name)

Gets the Tibia.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page on TibiaData.com.
Return type:str
classmethod get_world_list_url(world)

Gets the Tibia.com URL for the guild section of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page
Return type:str
classmethod get_world_list_url_tibiadata(world)

Gets the TibiaData.com URL for the guild list of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the guild’s information page on Tibia.com.

url_tibiadata

str – The URL to the guild on TibiaData.com.

ListedHouse

class tibiapy.ListedHouse(name, world, houseid, **kwargs)[source]

Represents a house from the house list in Tibia.com.

id

int – The internal ID of the house. This is used on the website to identify houses.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of house.

town

str – The town where the house is located.

size

int – The size of the house in SQM.

rent

int – The monthly cost of the house, in gold coins.

time_left

datetime.timedelta, optional – The number of days or hours left until the bid ends, if it has started. This is not an exact measure, it is rounded to hours or days.

highest_bid

int – The highest bid so far, if the auction has started.

classmethod list_from_content(content)[source]

Parses the content of a house list from Tibia.com into a list of houses

Parameters:content (str) – The raw HTML response from the house list.
Returns:
Return type:list of ListedHouse
Raises:InvalidContent` – Content is not the house list from Tibia.com
classmethod list_from_tibiadata(content)[source]

Parses the content of a house list from TibiaData.com into a list of houses

Parameters:content (str) – The raw JSON response from TibiaData
Returns:
Return type:list of ListedHouse
Raises:InvalidContent` – Content is not the house list from TibiaData.com
classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_url(house_id, world)

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the Tibia.com page of the house.

url_tibiadata

str – The URL to the TibiaData.com page of the house.

ListedNews

class tibiapy.ListedNews(news_id, title, news_type, category, date, **kwargs)[source]

Represents a news entry.

id

int – The internal ID of the news entry.

title

str – The title of the news entry. News tickers have a fragment of their content as a title.

category

NewsCategory – The category this belongs to.

category_icon

str – The URL of the icon corresponding to the category.

date

datetime.date – The date when the news were published.

type

NewsType – The type of news of this list entry.

classmethod list_from_content(content)[source]

Gets a list of news from the HTML content of the news search page.

Parameters:content (str) – The HTML content of the page.
Returns:List of news in the search results.
Return type:list of ListedNews
Raises:InvalidContent – If content is not the HTML of a news search’s page.
classmethod get_list_url()

Gets the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:The URL to the news archive page on Tibia.com.
Return type:str
classmethod get_url(news_id)

Gets the Tibia.com URL for a news entry by its id.

Parameters:news_id (int) – The id of the news entry.
Returns:The URL to the news’ page
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the Tibia.com page of the news entry.

ListedWorld

class tibiapy.ListedWorld(name, location=None, pvp_type=None, **kwargs)[source]

Represents a game server listed in the World Overview section.

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

transfer_type

TransferType – The type of transfer restrictions this world has.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

datetime.date – The date when BattlEye was added to this world. If this is None and the world is protected, it means the world was protected from the beginning.

experimental

bool – Whether the world is experimental or not.

premium_only

bool – Whether only premium account players are allowed to play in this server.

tournament_world_type

TournamentWorldType – The type of tournament world. None if this is not a tournament world.

classmethod get_list_url()[source]

Gets the URL to the World Overview page in Tibia.com

Returns:The URL to the World Overview’s page.
Return type:str
classmethod get_list_url_tibiadata()[source]

Gets the URL to the World Overview page in Tibia.com

Returns:The URL to the World Overview’s page.
Return type:str
classmethod list_from_content(content)[source]

Parses the content of the World Overview section from Tibia.com and returns only the list of worlds.

Parameters:content (str) – The HTML content of the World Overview page in Tibia.com
Returns:A list of the worlds and their current information.
Return type:list of ListedWorld
Raises:InvalidContent – If the provided content is not the HTML content of the worlds section in Tibia.com
classmethod list_from_tibiadata(content)[source]

Parses the content of the World Overview section from TibiaData.com.

Notes

Due to TibiaData limitations, the listed worlds lack some information. The following attributes are unavailable:

Parameters:content (str) – The JSON response of the worlds section in TibiaData.com
Returns:A list of the worlds and their current information.
Return type:list of ListedWorld
Raises:InvalidContent – If the provided content is the json content of the world section in TibiaData.com
classmethod get_url(name)

Gets the URL to the World’s information page on Tibia.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – URL to the world’s information page on Tibia.com.

url_tibiadata

str – URL to the world’s information page on TibiaData.com.

News

class tibiapy.News(news_id, title, content, date, category, **kwargs)[source]

Represents a news entry.

id

int – The internal ID of the news entry.

title

str – The title of the news entry.

category

NewsCategory – The category this belongs to.

category_icon

str – The URL of the icon corresponding to the category.

date

datetime.date – The date when the news were published.

content

str, optional – The raw html content of the entry.

thread_id

int, optional – The thread id of the designated discussion thread for this entry.

classmethod from_content(content, news_id=0)[source]

Gets a news entry by its HTML content from Tibia.com

Notes

Since there’s no way to obtain the entry’s Id from the page contents, it will always be 0. A news_id can be passed to set the news_id of the resulting object.

Parameters:
  • content (str) – The HTML content of the page.
  • news_id (int, optional) – The news_id belonging to the content being parsed.
Returns:

The news article found in the page.
Return type:

News
Raises:

InvalidContent – If content is not the HTML of a news’ page.
classmethod get_list_url()

Gets the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:The URL to the news archive page on Tibia.com.
Return type:str
classmethod get_url(news_id)

Gets the Tibia.com URL for a news entry by its id.

Parameters:news_id (int) – The id of the news entry.
Returns:The URL to the news’ page
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the Tibia.com page of the news entry.

World

class tibiapy.World(name, location=None, pvp_type=None, **kwargs)[source]

Represents a Tibia game server.

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

record_count

int – The server’s online players record.

record_date

datetime.datetime – The date when the online record was achieved.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

creation_date

str – The month and year the world was created. In YYYY-MM format.

transfer_type

TransferType – The type of transfer restrictions this world has.

world_quest_titles

list of str – List of world quest titles the server has achieved.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

datetime.date – The date when BattlEye was added to this world. If this is None and the world is protected, it means the world was protected from the beginning.

experimental

bool – Whether the world is experimental or not.

tournament_world_type

TournamentWorldType – The type of tournament world. None if this is not a tournament world.

online_players

list of OnlineCharacter. – A list of characters currently online in the server.

premium_only

bool – Whether only premium account players are allowed to play in this server.

creation_year

int – Returns the year when the world was created.

creation_month

ìnt – Returns the month when the world was created.

classmethod from_content(content)[source]

Parses a Tibia.com response into a World.

Parameters:content (str) – The raw HTML from the server’s information page.
Returns:The World described in the page, or None.
Return type:World
Raises:InvalidContent – If the provided content is not the html content of the world section in Tibia.com
classmethod from_tibiadata(content)[source]

Parses a TibiaData.com response into a World

Parameters:content (str) – The raw JSON content from TibiaData
Returns:The World described in the page, or None.
Return type:World
Raises:InvalidContent – If the provided content is not a TibiaData world response.
classmethod get_url(name)

Gets the URL to the World’s information page on Tibia.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – URL to the world’s information page on Tibia.com.

url_tibiadata

str – URL to the world’s information page on TibiaData.com.

WorldOverview

class tibiapy.WorldOverview(**kwargs)[source]

Container class for the World Overview section.

record_count

int – The overall player online record.

record_date

datetime.datetime – The date when the record was achieved.

worlds

list of ListedWorld – List of worlds, with limited info.

total_online

int – Total players online across all worlds.

classmethod get_url()[source]

Gets the URL to the World Overview page in Tibia.com

Returns:The URL to the World Overview’s page.
Return type:str
classmethod get_url_tibiadata()[source]

Gets the URL to the World Overview page in Tibia.com

Returns:The URL to the World Overview’s page.
Return type:str
classmethod from_content(content)[source]

Parses the content of the World Overview section from Tibia.com into an object of this class.

Parameters:content (str) – The HTML content of the World Overview page in Tibia.com
Returns:An instance of this class containing all the information.
Return type:WorldOverview
Raises:InvalidContent – If the provided content is not the HTML content of the worlds section in Tibia.com
classmethod from_tibiadata(content)[source]

Parses the content of the World Overview section from TibiaData.com into an object of this class.

Notes

Due to TibiaData limitations, record_count and record_date are unavailable object.

Additionally, the listed worlds in worlds lack some information when obtained from TibiaData. The following attributes are unavailable:

Parameters:content (str) – The JSON response of the worlds section in TibiaData.com
Returns:An instance of this class containing only the available worlds.
Return type:WorldOverview
Raises:InvalidContent – If the provided content is the json content of the world section in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

Auxiliary Classes

Auxiliary classes are used to hold certain data in a standardized way, in some cases, introducing additional methods and properties for their use.

AccountInformation

class tibiapy.AccountInformation(created, loyalty_title=None, position=None)[source]

Represents the account information of a character.

created

datetime.datetime – The date when the account was created.

position

str, optional – The special position of this account, if any.

loyalty_title

str, optional – The loyalty title of the account, if any.

to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

Achievement

class tibiapy.Achievement(name, grade, secret=False)[source]

Represents an achievement listed on a character’s page.

name

str – The name of the achievement.

grade

int – The grade of the achievement, also known as stars.

secret

:class:´bool´ – Whether the achievement is secret or not.

to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

CharacterHouse

class tibiapy.CharacterHouse(_id, name, world=None, town=None, owner=None, paid_until_date=None)[source]

Represents a House owned by a character.

id

int – The internal ID of the house. This is used on the website to identify houses.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

town

str – The town where the city is located in.

owner

str – The owner of the house.

paid_until_date

datetime.date – The date the last paid rent is due.

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_url(house_id, world)

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the Tibia.com page of the house.

url_tibiadata

str – The URL to the TibiaData.com page of the house.

ExpHighscoresEntry

class tibiapy.ExpHighscoresEntry(name, rank, vocation, value, level)[source]

Represents an entry for the highscores’s experience category.

This is a subclass of HighscoresEntry, adding an extra field for level.

name

str – The name of the character.

rank

int – The character’s rank in the respective highscores.

vocation

Vocation – The character’s vocation.

value

int – The character’s experience points.

level

int – The character’s level.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

Death

class tibiapy.Death(name=None, level=0, **kwargs)[source]

Represents a death by a character

name

str – The name of the character this death belongs to.

level

int – The level at which the death occurred.

killers

list of Killer – A list of all the killers involved.

assists

list of Killer – A list of characters that were involved, without dealing damage.

time

datetime.datetime – The time at which the death occurred.

by_player

bool – Whether the kill involves other characters.

killer

Killer – The first killer in the list.

This is usually the killer that gave the killing blow.

to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

GuildHouse

class tibiapy.GuildHouse(name, world=None, owner=None, paid_until_date=None)[source]

Represents a House owned by a guild.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

owner

str – The owner of the guildhall.

paid_until_date

datetime.date – The date the last paid rent is due.

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_url(house_id, world)

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

GuildInvite

class tibiapy.GuildInvite(name=None, date=None)[source]

Represents an invited character

name

str – The name of the character

date

datetime.date – The day when the character was invited.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

GuildMember

class tibiapy.GuildMember(name=None, rank=None, title=None, level=0, vocation=None, **kwargs)[source]

Represents a guild member.

rank

str – The rank the member belongs to

name

str – The name of the guild member.

title

str, optional – The member’s title.

level

int – The member’s level.

vocation

Vocation – The member’s vocation.

joined

datetime.date – The day the member joined the guild.

online

bool – Whether the member is online or not.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

GuildMembership

class tibiapy.GuildMembership(name, rank)[source]

Represents the guild information of a character.

name

str – The name of the guild.

rank

str – The name of the rank the member has.

classmethod get_url(name)

Gets the Tibia.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page on TibiaData.com.
Return type:str
classmethod get_world_list_url(world)

Gets the Tibia.com URL for the guild section of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page
Return type:str
classmethod get_world_list_url_tibiadata(world)

Gets the TibiaData.com URL for the guild list of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL to the guild’s information page on Tibia.com.

url_tibiadata

str – The URL to the guild on TibiaData.com.

HighscoresEntry

class tibiapy.HighscoresEntry(name, rank, vocation, value)[source]

Represents a entry for the highscores.

name

str – The name of the character.

rank

int – The character’s rank in the respective highscores.

vocation

Vocation – The character’s vocation.

value

int – The character’s value for the highscores.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

Killer

class tibiapy.Killer(name, player=False, summon=None)[source]

Represents a killer.

A killer can be:

  1. A creature.
  2. A character.
  3. A creature summoned by a character.
name

str – The name of the killer. In the case of summons, the name belongs to the owner.

player

bool – Whether the killer is a player or not.

summon

str, optional – The name of the summoned creature, if applicable.

url

str, optional – The URL of the character’s information page on Tibia.com, if applicable.

to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

LoyaltyHighscoresEntry

class tibiapy.LoyaltyHighscoresEntry(name, rank, vocation, value, title)[source]

Represents a entry for the highscores loyalty points category.

This is a subclass of HighscoresEntry, adding an extra field for title.

name

str – The name of the character.

rank

int – The character’s rank in the respective highscores.

vocation

Vocation – The character’s vocation.

value

int – The character’s loyalty points.

title

str – The character’s loyalty title.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

OnlineCharacter

class tibiapy.OnlineCharacter(name, world, level, vocation)[source]

Represents an online character.

name

str – The name of the character.

world

str – The name of the world.

vocation

Vocation – The vocation of the character.

level

int – The level of the character.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

OtherCharacter

class tibiapy.OtherCharacter(name, world, online=False, deleted=False)[source]

Represents other characters displayed in the Character’s information page.

name

str – The name of the character.

world

str – The name of the world.

online

bool – Whether the character is online or not.

deleted

bool – Whether the character is scheduled for deletion or not.

classmethod get_url(name)

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

RaceEntry

class tibiapy.RaceEntry(last_day_killed=0, last_day_players_killed=0, last_week_killed=0, last_week_players_killed=0)[source]

Represents the statistics of a race.

last_day_killed

int – Number of creatures of this race killed in the last day.

last_day_players_killed

int – Number of players killed by this race in the last day.

last_week_killed

int – Number of creatures of this race killed in the last week.

last_week_players_killed

int – Number of players killed by this race in the last week.

to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

Base Classes

The following classes are not meant to be used or instantiated, but are documented here for informational purposes.

They implement methods and properties that can be inherited by other classes to implement their functionality.

class tibiapy.abc.BaseCharacter[source]

Base class for all character classes.

Implements common properties methods for characters.

The following implement this class:

name

str – The name of the character.

url

str – The URL of the character’s information page on Tibia.com

url_tibiadata

str – The URL of the character’s information on TibiaData.com.

classmethod get_url(name)[source]

Gets the Tibia.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page.
Return type:str
classmethod get_url_tibiadata(name)[source]

Gets the TibiaData.com URL for a given character name.

Parameters:name (str) – The name of the character.
Returns:The URL to the character’s page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.BaseGuild[source]

Base class for Guild classes.

The following implement this class:

name

str – The name of the guild.

url

str – The URL to the guild’s information page on Tibia.com.

url_tibiadata

str – The URL to the guild on TibiaData.com.

classmethod get_url(name)[source]

Gets the Tibia.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page
Return type:str
classmethod get_url_tibiadata(name)[source]

Gets the TibiaData.com URL for a given guild name.

Parameters:name (str) – The name of the guild.
Returns:The URL to the guild’s page on TibiaData.com.
Return type:str
classmethod get_world_list_url(world)[source]

Gets the Tibia.com URL for the guild section of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page
Return type:str
classmethod get_world_list_url_tibiadata(world)[source]

Gets the TibiaData.com URL for the guild list of a specific world.

Parameters:world (str) – The name of the world.
Returns:The URL to the guild’s page.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.BaseHouse[source]

Base class for all house classes

The following implement this class:

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

classmethod get_url(house_id, world)[source]

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)[source]

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)[source]

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)[source]

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.BaseHouseWithId[source]

A derivative of BaseHouse

Implements the id attribute and dependant functions and properties.

The following implement this class:

id

int – The internal ID of the house. This is used on the website to identify houses.

name

str – The name of the house.

world

str – The name of the world the house belongs to.

status

HouseStatus – The current status of the house.

type

HouseType – The type of the house.

url

str – The URL to the Tibia.com page of the house.

url_tibiadata

str – The URL to the TibiaData.com page of the house.

classmethod get_list_url(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_list_url_tibiadata(world, town, house_type: tibiapy.enums.HouseType = HouseType.HOUSE)

Gets the URL to the house list on Tibia.com with the specified parameters.

Parameters:
  • world (str) – The name of the world.
  • town (str) – The name of the town.
  • house_type (HouseType) – Whether to search for houses or guildhalls.
Returns:

The URL to the list matching the parameters.
Return type:

str
classmethod get_url(house_id, world)

Gets the Tibia.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in Tibia.com
classmethod get_url_tibiadata(house_id, world)

Gets the TibiaData.com URL for a house with the given id and world.

Parameters:
  • house_id (int) – The internal id of the house.
  • world (str) – The world of the house.
Returns:
Return type:

The URL to the house in TibiaData.com
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.BaseNews[source]

Base class for all news classes

Implements the id attribute and common properties.

The following implement this class:

id

int – The internal ID of the news entry.

title

str – The title of the news entry.

category

NewsCategory – The category this belongs to.

category_icon

str – The URL of the icon corresponding to the category.

date

datetime.date – The date when the news were published.

url

str – The URL to the Tibia.com page of the news entry.

classmethod get_url(news_id)[source]

Gets the Tibia.com URL for a news entry by its id.

Parameters:news_id (int) – The id of the news entry.
Returns:The URL to the news’ page
Return type:str
classmethod get_list_url()[source]

Gets the URL to Tibia.com’s news archive page.

Notes

It is not possible to perform a search using query parameters. News searches can only be performed using POST requests sending the parameters as form-data.

Returns:The URL to the news archive page on Tibia.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.BaseWorld[source]

Base class for all World classes.

The following implement this class:

name

str – The name of the world.

status

str – The current status of the world.

online_count

int – The number of currently online players in the world.

location

WorldLocation – The physical location of the game servers.

pvp_type

PvpType – The type of PvP in the world.

transfer_type

TransferType – The type of transfer restrictions this world has.

battleye_protected

bool – Whether the server is currently protected with BattlEye or not.

battleye_date

datetime.date – The date when BattlEye was added to this world. If this is None and the world is protected, it means the world was protected from the beginning.

experimental

bool – Whether the world is experimental or not.

tournament_world_type

TournamentWorldType – The type of tournament world. None if this is not a tournament world.

premium_only

bool – Whether only premium account players are allowed to play in this server.

url

str – URL to the world’s information page on Tibia.com.

url_tibiadata

str – URL to the world’s information page on TibiaData.com.

classmethod get_url(name)[source]

Gets the URL to the World’s information page on Tibia.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page.
Return type:str
classmethod get_url_tibiadata(name)[source]

Gets the URL to the World’s information page on TibiaData.com.

Parameters:name (str) – The name of the world.
Returns:The URL to the world’s information page on TibiaData.com.
Return type:str
to_json(*, indent=None, sort_keys=False)

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str
class tibiapy.abc.Serializable[source]

Contains methods to make a class convertible to JSON.

Note

There’s no way to convert JSON strings back to their original object.
Attempting to do so may result in data loss.
to_json(*, indent=None, sort_keys=False)[source]

Gets the object’s JSON representation.

Parameters:
  • indent (int, optional) – Number of spaces used as indentation, None will return the shortest possible string.
  • sort_keys (bool, optional) – Whether keys should be sorted alphabetically or preserve the order defined by the object.
Returns:

JSON representation of the object.
Return type:

str

Exceptions

class tibiapy.TibiapyException[source]

Base exception for the tibiapy module.

All exceptions thrown by the module are inherited from this.

class tibiapy.InvalidContent[source]

Exception thrown when the provided content is unrelated for the calling function.

This usually means that the content provided belongs to a different website or section of the website. This serves as a way to differentiate those cases from a parsing that returned no results (e.g. Character not found)

In some cases this can mean that Tibia.com’s format has changed and the library needs updating.

class tibiapy.NetworkError(message, original=None)[source]

Exception thrown when there was a network error trying to fetch a resource from the web.

original

Exception – The original exception that caused this exception.

class tibiapy.Forbidden(message, original=None)[source]

A subclass of network error thrown when Tibia.com returns a 403 status code.

Tibia.com returns a 403 status code when it detects that too many requests are being done. This has its own subclass to let the user decide to treat this differently than other network errors.

Utility functions

These are functions used thorough the module and are not intended for public use.

tibiapy.utils.parse_tibia_datetime(datetime_str) → Optional[datetime.datetime][source]

Parses date and time from the format used in Tibia.com

Accepted format:

  • MMM DD YYYY, HH:mm:ss ZZZ, e.g. Dec 10 2018, 21:53:37 CET.
Parameters:datetime_str (str) – The date and time as represented in Tibia.com
Returns:The represented datetime, in UTC.
Return type:datetime.datetime, optional
tibiapy.utils.parse_tibia_date(date_str) → Optional[datetime.date][source]

Parses a date from the format used in Tibia.com

Accepted format:

  • MMM DD YYYY, e.g. Jul 23 2015
Parameters:date_str (str) – The date as represented in Tibia.com
Returns:The represented date.
Return type:datetime.date, optional
tibiapy.utils.parse_tibia_full_date(date_str) → Optional[datetime.date][source]

Parses a date in the fuller format used in Tibia.com

Accepted format:

  • MMMM DD, YYYY, e.g. July 23, 2015
Parameters:date_str (str) – The date as represented in Tibia.com
Returns:The represended date.
Return type:datetime.date, optional
tibiapy.utils.parse_tibiadata_datetime(date_dict) → Optional[datetime.datetime][source]

Parses time objects from the TibiaData API.

Time objects are made of a dictionary with three keys:
date: contains a string representation of the time timezone: a string representation of the timezone the date time is based on timezone_type: the type of representation used in the timezone key
Parameters:date_dict (dict) – Dictionary representing the time object.
Returns:The represented datetime, in UTC.
Return type:datetime.date, optional
tibiapy.utils.parse_tibiadata_date(date_str) → Optional[datetime.date][source]

Parses a date from the format used in TibiaData.

Parameters:date_str (str) – The date as represented in Tibia.com
Returns:The represended date.
Return type:datetime.date, optional
tibiapy.utils.parse_number_words(text_num)[source]

Parses the word representation of a number to a integer.

Parameters:text_num (str) – The text representation of a number.
Returns:The number represented by the string.
Return type:int
tibiapy.utils.try_datetime(obj) → Optional[datetime.datetime][source]

Attempts to convert an object into a datetime.

If the date format is known, it’s recommended to use the corresponding function This is meant to be used in constructors.

Parameters:obj (str, dict, datetime.datetime) – The object to convert.
Returns:The represented datetime, or None if conversion wasn’t possible.
Return type:datetime.datetime, optional
tibiapy.utils.try_date(obj) → Optional[datetime.date][source]

Attempts to convert an object into a date.

If the date format is known, it’s recommended to use the corresponding function This is meant to be used in constructors.

Parameters:obj (str, datetime.datetime, datetime.date) – The object to convert.
Returns:The represented date.
Return type:datetime.date, optional
tibiapy.utils.parse_tibiacom_content(content, *, html_class='BoxContent', tag='div', builder='lxml')[source]

Parses HTML content from Tibia.com into a BeautifulSoup object.

Parameters:
  • content (str) – The raw HTML content from Tibia.com
  • html_class (str) – The HTML class of the parsed element. The default value is BoxContent.
  • tag (str) – The HTML tag select. The default value is div.
  • builder (str) – The builder to use. The default value is lxml.
Returns:

The parsed content.
Return type:

bs4.BeautifulSoup, optional
tibiapy.utils.try_enum(cls: Type[T], val, default: D = None) → Union[T, D][source]

Attempts to convert a value into their enum value

Parameters:
  • cls (Enum) – The enum to convert to.
  • val – The value to try to convert to Enum
  • default (optional) – The value to return if no enum value is found.
Returns:

The enum value if found, otherwise None.
Return type:

obj
tibiapy.utils.parse_json(content)[source]

Tries to parse a string into a json object.

This also performs a trim of all values, recursively removing leading and trailing whitespace.

Parameters:content (str) – A JSON format string.
Returns:The object represented by the json string.
Return type:obj
Raises:InvalidContent – If the content is not a valid json string.
tibiapy.utils.parse_tibia_money(argument)[source]

Parses a string that may contain ‘k’ as thousand suffix.

Parameters:argument (str) – A numeric string.
Returns:The value represented by the string.
Return type:int