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
examine text, store
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
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
ItemWeapon: A selection of OSRS items are both equipable, and also weapons. The
ItemWeapon class has additional weapon-specific attributes including
weapon_types. Additionally, each weapon has an array of combat stances associated with it to determine the
attack_style and any
bonuses or combat
experience association. Finally, every weapon item also has the properties available in the
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
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!