Tibia ML Open XML initiative

Get dynamicly updated item, creature and quest information for your website

What is this?

This XML initiative is made based on the idea of making it easier for webdevelopers to get a library on their site with basic information about items, creatures and quests. Through the Open XML Initiative of Tibia ML webdevelopers can get this information from us delivered in an XML file so they don't need to update their sites library, so no more worries about that. If you own a Tibia fansite or plan to make one, keep on reading. If making sites is nothing for you, please go to the Tibia ML website. If you want to make use of this documentation knowledge of HTML or XHTML and a basic knowledge of PHP is needed.


What are the advantages of using this XML API?


Table of contents
What is XML?
» Reading XML using DOM
» Reading XML using the SAX parser
» Reading XML using regular expressions
Available information
» Get item information
» Get creature information
» Get quest information
Terms of usage
» Authorised users
Help needed?
Credits

What is XML?

XML stands for Extensible Markup Language. This is a set of rules for electronic presentation of documents. It's a simple data storage format based on tags and attributes for these tags. In the example below you can see how the first 2 quests look like in the quests XML file. The parent tag <quests> contains 2 <quest> tags. Each quest is build out of a <name>, <type>, <level>, <max_lvl>, <location>, <premium>, <duration> and <link> tag. Between the <name> tags for example you can see that Adept Camp Quest is the attribute, this means that the quests name is Adept Camp Quest. The article below will teach you how to read these XML files and use them in your webpage. <quests> 
    <quest> 
        <name>Adept Camp Quest</name> 
        <type>regular</type> 
        <level>0</level> 
        <max_lvl>0</max_lvl> 
        <location>Svargrond</location> 
        <premium>1</premium> 
        <duration>short</duration> 
        <link>http://en.tibiaml.com/quest/adept_camp_quest/</link> 
    </quest> 
    <quest> 
        <name>Against The Spider Cult Quest</name> 
        <type>regular</type> 
        <level>0</level> 
        <max_lvl>0</max_lvl> 
        <location>Edron</location> 
        <premium>1</premium> 
        <duration>short</duration> 
        <link>http://en.tibiaml.com/quest/against_the_spider_cult_quest/</link> 
    </quest>
</quests>
There are tree methods available to read XML files using PHP which we'll all discuss. A first method is using DOM, the second one makes use of a SAX parser and the final method is based on regular expressions. If you want to use the XML files for other programming languages, you'll have to write your own code or search the web for it.

Reading XML using DOM

DOM or Document Object Model is a convention designed to allow interaction between HTML or XHTML and XML. This is the easiest way to read XML files but it needs to be enabled on your server (it's available on most servers). If it's currently not available on your server, contact your server administrator and ask to activate it. The example below, illustrating the usage of DOM on the above mentioned XML file is written in PHP and will show the quest name followed by the type and level. <?php
    
// Open the DOM library
    
$doc = new DOMDocument();
    
    
// Load the XML file
    
$doc->load('http://xml.tibiaml.com/library.php?type=quests');
    
    
// Get the quests from the XML
    
$quests $doc->getElementsByTagName("quest");
    
    
// Loop the quests
    
foreach ($quests AS $quest) {
        
// Get quests name
        
$names $quest->getElementsByTagName("name");
        
$name $names->item(0)->nodeValue;
        
        
// Get quests type
        
$types $quest->getElementsByTagName("type");
        
$type $types->item(0)->nodeValue;
        
        
// Get quests minimum level required
        
$levels $quest->getElementsByTagName("level");
        
$level $levels->item(0)->nodeValue;
        
        
/* You can get additional information on the same
        way as the name, type and level is done */
        
        // Display the quest on the page
        
echo $name " is a " $type " quest 
        with a minimum level of " 
$level ".<br />";
    }
?>
This code executed on the XML file on top of this page will give the next result when executed: Adept Camp Quest is a regular quest with a minimum level of 0.
Against The Spider Cult Quest is a regular quest with a minimum level of 0.

Reading XML using the SAX parser

If DOM is not available on your server you can use the SAX (Simple API for XML) parser. In most PHP installations the SAX parser is included. The SAX parser is a serial access parser API for XML that is very lightweighted so it can be used for big files but on the other hand the code is quite complicated compared to the DOM and regular expression parser.

A parser which implements SAX (ie, a SAX Parser) functions as a stream parser, with an event-driven API. The user defines a number of callback methods that will be called when events occur during parsing. Events are fired when each of these XML features are encountered, and again when the end of them is encountered. XML attributes are provided as part of the data passed to element events. SAX parsing is unidirectional; previously parsed data cannot be re-read without starting the parsing operation again. <?php
    
// Create an array and an empty variable
    
$g_quests = array();
    
$g_elem null;
    
    
// Start element function
    
function startElement($parser$name$attrs) {
        global 
$g_quests$g_elem;
        if (
$name == 'QUEST'$g_quests[] = array();
        
$g_elem $name;
    }
    
    
// End element function
    
function endElement($parser$name) {
        global 
$g_elem;
        
$g_elem null;
    }
    
    
// Text data function
    
function textData($parser$text) {
        global 
$g_quests$g_elem;
        if (
$g_elem == 'NAME' OR $g_elem == 'TYPE' OR $g_elem == 'LEVEL') {
            
$g_quests[count($g_quests)-1][$g_elem] = $text;
        }
    }
    
    
// Create an XML parser
    
$parser xml_parser_create();
    
    
// Set up start and end element handlers
    
xml_set_element_handler($parser"startElement""endElement");
    
    
// Set up character data handler
    
xml_set_character_data_handler($parser"textData");
    
    
// Open file
    
$f fopen('http://xml.tibiaml.com/library.php?type=quests''r');
    
    
// Read file and loop results
    
while ($data fread($f4096)) {
        
// Start parsing the XML document
        
xml_parse($parser$data);
    }
    
    
// Drop the XML parser
    
xml_parser_free($parser);
    
    
// Loop the generated array 
    
foreach ($g_quests as $quest) { 
        
// Display the quest on the page 
        
echo $quest['NAME'] . " is a " $quest['TYPE'] . " quest  
        with a minimum level of " 
$quest['LEVEL'] . ".<br />"
    }
?>
When executing the above file it will again return: Adept Camp Quest is a regular quest with a minimum level of 0.
Against The Spider Cult Quest is a regular quest with a minimum level of 0.

Reading XML using regular expressions

Reading XML files using regular expressions is very easy, the entire file is loaded into a string and then the script loops the file and reads every block. Regular expressions are always available on your server if you have PHP support. Next to these advantages reading XML files with regular expressions has one big disadvantage, when the XML file is bad formatted your script will get wrong information from the XML file resulting in a lot of problems. Only use this method if the previously mentioned methods are not available. <?php
    
// Create an empty string
    
$xml "";
    
    
// Open the XML file
    
$f fopen('http://xml.tibiaml.com/library.php?type=quests''r');
    
    
// Read file and loop results
    
while ($data fread($f4096)) { 
        
// Add data to the string
        
$xml .= $data;
    }
    
    
// Close the file
    
fclose$f );
    
    
// Find all quests
    
preg_match_all("/\<quest\>(.*?)\<\/quest\>/s"$xml$questblocks);
    
    
// Loop the quests
    
foreach ($questblocks[1] as $block)    {
        
// Get quest name, type and level
        
preg_match_all("/\<name\>(.*?)\<\/name\>/"$block$name);
        
preg_match_all("/\<type\>(.*?)\<\/type\>/"$block$type);
        
preg_match_all("/\<level\>(.*?)\<\/level\>/"$block$level);
        
        
/* You can get additional information on the same
        way as the name, type and level is done */
        
        // Display the quest on the page
        
echo $name[1][0] . " is a " $type[1][0] . " quest 
        with a minimum level of " 
$level[1][0] . ".<br />";
    }
?>
When executing it will return the same then the previous 2 methodes, which is: Adept Camp Quest is a regular quest with a minimum level of 0.
Against The Spider Cult Quest is a regular quest with a minimum level of 0.

Available information

We have information available about items, creatures and quests. More information might be added later but if you need something different, feel free to contact us.

Get item information

You can access information about items by accessing the following URL with your XML parser: http://xml.tibiaml.com/library.php?type=items To get item information in a specific category (for example only armors), you can access the following URL: http://xml.tibiaml.com/library.php?type=items&cat=armors The available categories (in alphabetic order) you can get information from are: category name [- description]

ammunition - ammunition for distance weapons
amulets
armors
axes
boots
bossdrops - special bossmonster items
clubs
containers - bags, backpacks...
products - creature products
decoration
deleted - deleted items
distance - distance weapons
dolls - dolls & bears
flowers
food
furniture
tokens - game tokens
gems - gems and other valuables
helmets
instruments
keys
legs
light - light sources, e.g. torch
liquids - liquids and potions
others - items not in any of the above categories
paperware
party - party items
rings
rods
shields
specials - special items
swords
tools
trash
trophies
wands
The information available about items is the next: tag name - description

name - name of the item
picture - URL of the items picture
type - item type (swords, armors, gems...)
weight - weight of the item in oz
armor - armor of the item (for armors, legs, boots...), is empty if item has no armor
attack - items attack (for weapons), is empty if item has no attack
defense - items defense (for weapons and shields), is empty if item has no defense
hands - hands needed to wield the weapon, is empty if item is no weapon
link - link of the Tibia ML page about this item, link here for more info

Get creature information

For creature information you need to parse the following URL with XML: http://xml.tibiaml.com/library.php?type=creatures The following creature information is available to you: tag name - description

name - creature name
picture - creature picture URL
exp - experience creature gives when killed
hp - creatures hit points
mana_summon - mana needed to summon this creature, blank if not summonable
mana_convince - mana needed to convince this creature, blank if not convincable
screenshot - 200x200 creature screenshot URL
link - Tibia ML link for more creature information and loot statistics

Get quest information

The same applies to quests. You can access the quest information by accessing the following URL with your XML parser: http://xml.tibiaml.com/library.php?type=quests On our XML quest feed you can find the following quest information: tag name - description

name - name of the quest
type - quest type (regular, outfit, addon...)
level - minimum level needed to do the quests, 0 if there is no level required
max_lvl - maximum level to do the quest, 0 if any level can do the quest
location - nearest city or area
premium - premium required (1 if required, 0 if not)
duration - time needed to complete the quest (short, medium or long)
link - link to the Tibia ML quest guide, link here for all quest info

Terms of usage

To make authorised usage of our Open XML Initiative you need to contact us and tell us how you want to use our XML and how often you'll request our XML pages. We'll then add you to our authorised users list.

Our requirements:

Any violation of our terms gives us permission to exlcude your from XML parsing without prior notice.

Authorised users

The following users have contacted us and are allowed to make use of our XML API:

TibiaNordic.com - library
Tibiacity.org - library

Help needed?

Need help developing your XML pages? Contact us and we'll do our best to assist you with the development of your webpages. Note that you'll need some basic knowledge of HTML, CSS and PHP; we won't design webpages for you.

Credits

Jack Herrington, IBM. (2005). Reading and writing the XML DOM with PHP". (view)
Wikipedia. (2008). Simple API for XML. (view)