Skip to content
A complete and up-to-date database of Old School Runescape (OSRS) items
Python Shell
Branch: master
Clone or download
Latest commit b054b7c Aug 23, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
data Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019
docs Adding the monsters database (finally!) (#141) Aug 22, 2019
extraction_tools_cache Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019
extraction_tools_wiki Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019
items_builder Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019
monsters_builder Adding the monsters database (finally!) (#141) Aug 22, 2019
osrsbox Adding the monsters database (finally!) (#141) Aug 22, 2019
scripts Adding the monsters database (finally!) (#141) Aug 22, 2019
test Adding the monsters database (finally!) (#141) Aug 22, 2019
.gitattributes fix line endings Feb 24, 2019
.gitignore Some minor bug fixes to wiki parsing scripts, found when preparing mo… Aug 14, 2019
.travis.yml Added script to extract Weapon/Types data. Amalgamated requirements.t… Apr 17, 2019 Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019
LICENSE Changed project license to GPL3 Sep 29, 2018 Update package contents (#89) Mar 28, 2019 Added JSON schema parser to help automate documentation which closes #… Aug 19, 2019 Weekly cache and wiki data update. Updated items builder for various … Aug 3, 2019
requirements.txt No weekly game update, so only an update to OSRS Wiki data. Pushed Py… May 11, 2019
setup.cfg Added script to extract Weapon/Types data. Amalgamated requirements.t… Apr 17, 2019 Weekly cache and wiki update. Weekly item database regeneration. Push… Aug 22, 2019


Build Status PyPI - Python Version

PyPI version PyPI - Downloads

A complete and up-to-date database of Old School Runescape (OSRS) items

This repository hosts a complete and up-to-date database of every item in OSRS. Complete means it holds every single item in OSRS. Up-to-date means this database is updated after every weekly game update to ensure accurate information.

The item database has extensive properties for each item: a total of 21 properties for every item, and an additional 17 properties for equipable items. Each item has properties including whether an item is tradeable, stackable, or equipable or if the item is members only or an item associated with a quest. For any equipable item, there are additional properties about combat stats the item has; for example, what slash attack bonus, magic defence bonus or prayer bonus an item provides.

The item database is accessible using two primary methods:

  1. A Python PyPi package named osrsbox

Current development is working towards adding a similar database for monsters.

Table of Contents

Additional Documentation

For detailed information about the project see the OSRSBox website for the official project page, and the Database tag to find blog posts about the project:

Project Requirements

For the osrsbox package (see below) and any scripts in this repository you will need:

  • Python 3.6 or above - Dataclasses package (if Python is below 3.7)

If using this repository (the development version), you will also need a variety of Python packages in addition to the mandatory dataclasses package. These are documented in the requirements.txt file. It is recommended to use virtualenv to setup your environment, then install the specified requirements using:

pip install -r requirements.txt

The osrsbox Package

If you just want to access the item database programmatically, it is probably more sensible to use the osrsbox package available from PyPi. Basically, you can load the item database and process item objects and their properties.

This repo hosts the source code for the package in the osrsbox folder, while the other folders in this repository are used to store essential data and Python modules to build the item database. You can install the osrsbox package using pip:

pip install osrsbox

More information regarding using the osrsbox Python package can be found in the osrsbox package README file.

The osrsbox-db JSON API

This project also includes an Internet-accessible JSON API for all items in the item database. The JSON API was originally written for the osrsbox-tooltips project but has been used for a variety of other projects. The JSON API is useful when you do not want to write a program in Python, but would like to fetch the item database information programmatically. A key example is a web application.

The JSON API is available in the docs folder in this repository. More information regarding using the osrsbox-db JSON API can be found in the osrsbox-db README file.

Item Database Schema

Technically, the osrsbox-db is not really a database - more specifically it should be called a data set. Anyway... the contents in the item database need to adhere to a specified structure, as well as specified data types for each property. This is achieved (documented and tested) using the JSON Schema project. The JSON schema is provided with this project in the item_schema.json file in the test directory. The JSON schema is useful to determine:

  • The properties that are available for each item
  • Mandatory properties for each item (specified in the required property)
  • The data types of each property (e.g., boolean, integer, string, null)

A more user-friendly table of the currently available item properties can be found in the osrsbox package README file.

Project Information

This section contains additional information about the osrsbox-db project.

Summary of Project Structure

  • data: Collection of useful data files used in the osrsbox-db project.
  • docs: The publicly accessible item database available through this repo or by using the JSON API. This folder contains the actual item database that is publicly available, or browsable within this repository.
  • extraction_tools_cache: An up-to-date OSRS cache dump (compressed) with associated tools used in other parts in this project.
  • extraction_tools_wiki: Collection of Python modules to extract data from the new (non-Wikia) OSRS Wiki site. There is also dumped data (category page titles and raw wiki text) for items, quests, and monsters that are somewhat-regularly updated.
  • items_builder: Collection of Python scripts to build the item database. The script is the primary entry point.
  • osrsbox: The Python package:
    • items_api: The Python API for interacting with the items database. Has modules to load all items in the database, iterate through items and access the different item properties.
    • items_api_examples: A collection of simple Python scripts that use the items_api to provide an example of what can be achieved and how to use the items database.
  • scripts: A selection of scripts (using Python and BASH) to help automate common tasks.
  • test: A collection of unit tests.
  • Document of items added, removed or changed in each weekly game update that has been added to the database.

Project Feedback

I would thoroughly appreciate any feedback regarding the osrsbox-db project, especially problems with the inaccuracies of the data provided. So if you notice any problem with the accuracy of item property data, could you please let me know. The same goes for any discovered bugs, or if you have a specific feature request. The best method is to open a new Github issue in the project repository.

Project Contribution

This project would thoroughly benefit from a contribution from additional developers. Please feel free to submit a pull request if you have code that you wish to contribute - I would thoroughly appreciate the helping hand. For any code contributions, the best method is to open a new GitHub pull request in the project repository. Also, feel free to contact me (e.g., email) if you wish to discuss contribution before making a pull request. If you are not a software developer and want to contribute, even something as small as Staring this repository really makes my day and keeps me motivated!

Project License

The osrsbox-db project is released under the GNU General Public License version 3 as published by the Free Software Foundation. You can read the LICENSE file for the full license, check the GNU GPL page for additional information, or check the [tl;drLegal]( documentation for the license explained in simple English. The GPL license is specified for all source code contained in this project. Other content is specified under GPL if not listed in the Exceptions to GPL below.

Exceptions to GPL

Old School RuneScape (OSRS) content and materials are trademarks and copyrights of JaGeX or its licensors. All rights reserved. OSRSBox and the osrsbox-db project is not associated or affiliated with JaGeX or its licensors.

Additional data to help build this project is sourced from the OSRS Wiki. This primarily includes item metadata. As specified by the Weird Gloop Copyright page, this content is licensed under CC BY-NC-SA 3.0 - Attribution-NonCommercial-ShareAlike 3.0 Unported license.

Project Attribution

The osrsbox-db project is a labor of love. I put a huge amount of time and effort into the project, and I want people to use it. That is the entire reason for its existence. I am not too fussed about attribution guidelines... but if you want to use the project please adhere to the licenses used. Please feel free to link to this repository or my OSRSBox website if you use it in your project - mainly so others can find it, and hopefully use it too!

You can’t perform that action at this time.