This post presents a quick introduction to the Python API that I have authored for my OSRSBox Item Database. The database contains every item in Old School RuneScape (OSRS) with lots of properties for each item, including alchemy values, examine text, quest status and item bonuses and equipment properties.
The API is a simple implementation that makes processing the item database easier. You can load the database, and interact with each item as an object. This makes it simple and fast to author basic Python scripts to extract or manipulate item information from the database. You can also do funky things such as import the item “database” into an actual database such as MySQL or MongoDB. I prefer to write Python scripts, but both of these options could be very useful.
To use the OSRSBox Item API you only need the following requirements:
Only the standard Python installation is required, and the API (by default) only uses the dataclasses
library when using Python 3.6 (but not 3.7 as it is standard). The API has been written and tested in Python version 3.6 and Python version 3.7.
The OSRSBox database (osrsbox-db) repository hosts a variety of code. The programs to scrape the OSRS Wiki are included, as well as the programs used to build, manage and update the database. This means the repository has a bunch of subfolders. The Python API is available inside the osrsbox
folder, in the osrsbox-db repository. However, you do not need to clone the repository to use the API… You can simply use pip
to install the osrsbox
package. The osrsbox
package is hosted on PyPi and can be installed using:
Each item is represented by Python objects, specifically using Python dataclasses. There are three types of objects that can be used to represent part of an in-game OSRS item:
ItemDefinition
: An item that is not equipable, and not a weapon. This object type includes basic item metadata such as id
, name
, examine
text, store cost
, high_alch
and low_alch
values and quest
association. Every item object in the database has these properties.
ItemEquipment
: Many items in OSRS are equipable, this includes armour and other wearable items. Any equipable item (that is not a weapon) is stored as an ItemEquipment
object including attributes such as attack_slash
, defence_crush
and melee_strength
values. Additional information about equipable items include skill requirements
to wear armour or wield weapons, and item slot
properties. Finally, every equipable item also has all the properties available in the ItemDefinition
class.
ItemWeapon
: A selection of OSRS items are both equipable, and also weapons. The ItemWeapon
class has additional weapon-specific attributes including attack_speed
and weapon_types
. Additionally, each weapon has an array of combat stances associated with it to determine the combat_style
, attack_type
, attack_style
and any bonuses
or combat experience
association. Finally, every weapon item also has the properties available in the ItemDefinition
and ItemEquipment
classes.
Any tool in the osrsbox/items_api_examples
folder that is an example program. Have a look at some of these scripts if you want to see some more working examples of using the API.
This section presents a short and simple example of how to use the Python API to import the API classes, load the item database, and then loop through every item.
To use the Python API, you must import the items_api
class. If this class is imported, the remaining API classes are automatically imported. The following code will import the required Python classes to load and process item metadata.
Once you have imported the API class you are ready to load in the items. The API will handle this for you, and attempts to hide all the processing from the end-user. The example below loads the item database using the items_api
class.
Once you have the item database loaded you can process the items. In the previous example, we loaded the item database into an object called all_db_items
. The API has built-in capability to iterate the items in this object to make processing easy. As a simple example, the code below loops over every item in the loaded database, and prints the item ID number and item name (if it has a name - as some item IDs do not).
In the previous section, we simply printed the item ID number and item name. However, this is a very simple example. Since the item database has a lot of properties for each item, we can write quite complex queries. However, to achieve this you need to be able to access the item properties. Below is a list of print statements for the properties of every item property in the database:
The above list only prints the information in each property to the terminal. But the list gives an idea of how to use each item object. In addition, you can fetch more metadata about an item if it is equipable. This is an easy process using the API, as outlined by the code snippet below:
In the above code, the if item.equipable_by_player:
statement checks to see if an item is equipable. If it is, then you can access the item.equipment
object. Instead of listing all the properties available in each object in this post, I recommend checking the OSRSBox Database project page on PyPi which has a table of all the properties available. However, as a simple example, you can fetch the melee strength bonus of an equipable item using the code below:
The previous sections discussed the technical details of how to use the Python API for the OSRSBox item database. This section provides a couple of small examples of some useful scripts to give you more of an idea about how to use the database contents in a useful manner.
The example below loops over all of the items and determines if an item has a buy limit associated with it and then prints the item name and the item buy limit value.
The example below is a little more complex. It loops over all of the items and determines if an item is equipable. It then adds the attack slash value to a dictionary where the key is the attack slash value and appends the item name to a list which is the value. It then prints out a sorted list (highest to lowest) of attack slash value and item names. Basically, it prints a list of the items with the highest to lowest attack slash bonuses.
The output from the code above is a very long list of items! The first line printed are the items with the highest slash attach bonuses. Out of interest, these are the godswords from God wars dungeon bosses, as listed below.
This post only touched the surface of the different things you can do with the OSRSBox database of items. Hopefully, it provided some guidance to help you write some simple Python scripts to process the items and extract useful information from the raw data.
I am really open to feedback on this project. If you find any issues with the item database API, please let me know. Same goes for any inaccuracies in the database contents. There are over 20,000 items - so it is difficult to manage. But members of the OSRS community have already been giving feedback and bug reports which make this is a much better project! I am also thinking of ways to extend the Python API at the moment to provide more functionality and simplify data processing - so please let me know if you have any feedback.
Make sure to check out the OSRSBox Database project page for more information. And also the OSRSBox GitHub repository to check for current issues and to make pull requests if you have code/fixes to add to the project.
Until next time, happy scaping everyone!