API Endpoints¶

Real-Time API¶

This is the parent class for all queries to the Real Time API for OSRS. It is recommended to use one of the child classes documented below for standard usage.

For full documentation of the Real Time API routes and options, see the Real-Time documentation.

class rswiki_wrapper.osrs.RealTimeQuery(route='', game='osrs', user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

A class for making real-time price queries to the RuneScape Wiki API.

This class extends the WikiQuery class and provides specific functionality for making queries to the real-time price endpoints of the RuneScape Wiki API. The class provides options for querying the latest prices, mapping item IDs to names, querying average prices over given time periods, and requesting timeseries data for specific items.

For using each route, it is best practice to use the respective child classes.

Parameters:

route (str, optional) – The specific route to query within the endpoint. Can be one of 'latest', 'mapping', '5m', ‘1h’`, or 'timeseries'.
game (str, optional) – The specific game mode to query. Can be one of 'osrs', 'dmm', or 'fsw'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.
**kwargs – Additional keyword arguments to include in the query. Varies by route.

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

json¶

The raw JSON formatted response from the API. Formatted as OrderedDict for all Real-Time queries.

Type:: dict

Route: Latest¶

class rswiki_wrapper.osrs.Latest(game='osrs', user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

A class for querying the latest real-time prices from the RuneScape Wiki API. This class extends the RealTimeQuery class and provides specific functionality for making queries to the 'latest' route of the real-time price API.

Parameters:

game (str, optional) – The specific game mode to query. Can be one of 'osrs', 'dmm', or 'fsw'. Default 'osrs'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

Keyword Arguments:

id (str, optional) – The itemID to query if only one itemID is desired.

Note

It is best practice to query all item ids (do not provide a kwarg) and to loop through the .content object for specific IDs you require. This requires only one query to the RSWiki API.

content¶

A dict obj where the keys are all itemIDs and the values are dicts

content format:

{
    item_id :
        {
            'high': insta_buy_price (int),
            'highTime': insta_buy_time_unix (int),
            'low': insta_sell_price (int),
            'lowTime': insta_sell_time_unix (int)
        },
    # New key for next item_id
}

Type:: dict

Example

Example to get a specific item ID:

>>> query = Latest('osrs', user_agent='My Project - me@example.com')
>>> query.content['2']
{'high': 152, 'highTime': 1672437534, 'low': 154, 'lowTime': 1672437701}

Route: Mapping¶

class rswiki_wrapper.osrs.Mapping(game='osrs', user_agent='RS Wiki API Python Wrapper - Default')¶

A class for querying the item mappings from the RuneScape Wiki API.

This class extends the RealTimeQuery class and provides specific functionality for making queries to the 'mapping' route of the real-time API.

Parameters:

game (str, optional) – The specific game mode to query. Can be one of 'osrs', 'dmm', or 'fsw'. Default 'osrs'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

content¶

A list of all item mapping information

content format:

[
    {
        'examine': examine_text (str),
        'highalch': high_alch (int),
        'icon': icon_name (str),
        'id': item_id (int),
        'limit': ge_limit (int),
        'lowalch': low_alch (int),
        'members': members (bool),
        'name': name (str),
        'value': ge_price (int)
    }
    # Next index is next item
]

Type:: list

Example

Example to get mapping information for an item:

>>> query = Mapping('osrs', user_agent='My Project - me@example.com')
>>> query.content[0]
{'examine': 'Fabulously ancient mage protection enchanted in the 3rd Age.', 'id': 10344, 'members': True,
'lowalch': 20200, 'limit': 8, 'value': 50500, 'highalch': 30300, 'icon': '3rd age amulet.png', 'name': '3rd age amulet'}

Example to create an item hash map:

>>> query = Mapping('osrs', user_agent='My Project - me@example.com')
>>> item_map = {}
>>> for d in query.content:
>>>     item_map[str(d['id'])] = d
>>>     item_map[d['name']] = d
>>> item_map['Coal']['id']
453

Route: Avg Price¶

class rswiki_wrapper.osrs.AvgPrice(route, game='osrs', user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

A class for querying the average real-time prices from the RuneScape Wiki API.

This class extends the RealTimeQuery class and provides specific functionality for making queries to the '5m' or '1h' routes of the real-time API.

Parameters:

route (str) – The route to query. Must be ‘5m’ or ‘1h’.
game (str, optional) – The specific game mode to query. Can be one of 'osrs', 'dmm', or 'fsw'. Default 'osrs'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

Keyword Arguments:

timestamp (str, optional) – The timestamp (UNIX formatted) to begin the average calculation at.

content¶

A dict obj where the keys are all itemIDs and the values are dicts

content format:

{
    item_id :
        {
            'avgHighPrice': average_instabuy_price (int),
            'avgLowPrice': average_instasell_price (int),
            'highPriceVolume': instabuy_volume (int),
            'lowPriceVolume': instasell_volume (int)
        },
    # New key for next item_id
}

Type:: dict

Example

Example to get a specific item ID:

>>> query = AvgPrice('5m', 'osrs', user_agent='My Project - me@example.com')
>>> query.content['2']
{'avgHighPrice': 158, 'highPriceVolume': 127372, 'avgLowPrice': 159, 'lowPriceVolume': 11785}

Route: Time-Series¶

class rswiki_wrapper.osrs.TimeSeries(game='osrs', user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

A class for querying the time-series real-time prices from the RuneScape Wiki API.

This class extends the RealTimeQuery class and provides specific functionality for making queries to the: 'timeseries' route of the real-time price API. This provides timeseries information for a single Item. This basically provides AvgPrice information over a series of points. Length of content provided is dependent on continuity of data and timestep selected.

Parameters:

game (str, optional) – The specific game mode to query. Can be one of 'osrs', 'dmm', or 'fsw'. Default 'osrs'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

Keyword Arguments:

id (str, required) – The itemID to provide timeseries data for.
timestep (str, required) – The period of the time-series data to retrieve. Valid values are '5m', '1h', or '6h'.

content¶

A dict obj where the keys are all itemIDs and the values are dicts

content format:

[
    {
        'avgHighPrice': average_instabuy_price (int),
        'avgLowPrice': average_instasell_price (int),
        'highPriceVolume': instabuy_volume (int),
        'lowPriceVolume': instasell_volume (int),
        'timestamp': unix_timestamp (int)
    },
    # New index for next timestep
]

Type:: dict

Example

Example to get a specific item ID:

>>> query = TimeSeries('osrs', user_agent='My Project - me@example.com', id='2', timestep='5m')
>>> query.content[0]
{'timestamp': 1672330200, 'avgHighPrice': 162, 'avgLowPrice': 155, 'highPriceVolume': 204403, 'lowPriceVolume': 11966}

Weird Gloop API¶

This is the parent class for all queries to the Weird Gloop API for Exchange and Runescape information. It is recommended to use one of the child classes documented below for standard usage.

For full documentation of the Weird Gloop API routes and endpoints as well as query testing, see the Weird Gloop documentation.

class rswiki_wrapper.wiki.WeirdGloop(route: str, game: str, endpoint: str, user_agent: str, **kwargs)¶

This class extends the WikiQuery class to make queries to the Weird Gloop API. For general usage, it is recommended to use the specific Exchange or Runescape child classes.

Parameters:

route (str) – The route of the Weird Gloop API to query.
game (str) – The game to query in the Weird Gloop API.
endpoint (str) – The endpoint of the Weird Gloop API to query.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.
**kwargs – Additional keyword arguments to pass, depending on the specific query

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

Route: Exchange¶

class rswiki_wrapper.wiki.Exchange(game, endpoint, user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

This class extends the WeirdGloop class to make queries to the exchange history endpoint of the Weird Gloop API.

Parameters:

game (str) – The game to query in the Weird Gloop API. Valid options are 'rs', 'rs-fsw-2022', 'osrs', 'osrs-fsw-2022'.
endpoint (str) – The endpoint of the Weird Gloop API to query. Valid options are 'latest', 'all', 'last90d', and 'sample'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

Keyword Arguments:

id (str) – The itemID or a trade index like GE Common Trade Index
name (str) – The exact Grand Exchange item name.

Note

Only id or name can be provided as kwargs, not both.
If using the latest endpoint, multiple items can be specified using pipes “|” like id='2|6'
If using all, last90d, and sample endpoints, multiple item ID or names cannot be provided.

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

json¶

The raw JSON formatted response from the API

Type:: dict

content¶

The parsed content of the request. Formatted as follows. item is either the item name or item ID that you provided to the request. Sample content format:

{
item (str):
    [
        {
            'id' : item_id (str),
            'timestamp': timestamp (str),
            'price': price (int),
            'volume': volume (int),
        },
        # A new dict for each timestamp
    ]
}

Type:: dict

Examples

Example usage of latest endpoint:

>>> query = Exchange('osrs', 'latest', user_agent='My Project - me@example.com', id='2|6')
>>> query.content['2'][0]['id']
'2'

Example usage of all endpoint:

>>> query = Exchange('osrs', 'all', user_agent='My Project - me@example.com', name='Coal')
>>> query.content['Coal'][0]['id']
'453'

Route: Runescape¶

class rswiki_wrapper.wiki.Runescape(endpoint, user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

This class extends the WeirdGloop class to make queries to the general endpoints of the Weird Gloop API for Runescape information.

Parameters:

endpoint (str) – The endpoint of the Weird Gloop API to query. Valid options are "vos", 'vos/history', 'social', 'social/last', 'tms/current', 'tms/next', and 'tms/search'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

Keyword Arguments:

lang (str) – Required for 'tms/current' and 'tms/next' endpoints. Optional for 'tms/search'. Valid values are 'en', 'pt', 'id' (item IDs only), and 'full' (all information).
page (str) – Required for 'vos/history' and 'social' endpoints. The page number is formatted as a string.
start (str) – Required for 'tms/search'. Date string or 'today'.
id (str) – Optional for 'tms/search'. The item ID to search for.
name (str) – Optional for 'tms/search'. The item name to search for.
number (str) – Optional for 'tms/search'. The number of results to return
end (str) – Optional for 'tms/search'. Date string or 'today'.

Note

For 'tms/search' endpoint, either 'id' or 'name' is required (but not both) and either 'end' or 'number' is required (but not both).

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

json¶

The raw JSON formatted response from the API

Type:: dict

content¶: The parsed content of the request. Generally either a list of multiple results or a single result in dict format, depending on the endpoint used.

Examples

Example usage of tms/search endpoint to search for instances where item ID 42274 was active:

>>> query = Runescape('tms/search', user_agent='My Project - me@example.com', lang='full', start='2022-01-01', end='2022-01-07', id='42274')
>>> query.content[0]['items'][0]
{'id': '42274', 'en': 'Uncharted island map (Deep Sea Fishing)', 'pt': 'Mapa da ilha inexplorada (Pesca em Alto Mar)'}

Example usage of social endpoint:

>>> query = Runescape('social', user_agent='My Project - me@example.com', page='1')
>>> query.content[0].keys()
dict_keys(['id', 'url', 'title', 'excerpt', 'author', 'curator', 'source', 'image', 'icon', 'expiryDate', 'datePublished', 'dateAdded'])

static _check_kwargs(**kwargs)¶

This method checks the keyword arguments passed to the Runescape class for the 'tms/search' endpoint to ensure that they are valid and do not conflict with each other.

Parameters:: **kwargs – The keyword arguments to check.
Returns:: Whether the keyword arguments are valid and do not conflict.
Return type:: bool

Media Wiki API¶

This is the class for all queries to the Media Wiki API for all information in the RSWiki not covered by Real-Time and Weird Gloop APIs. There are a handful of helpful methods in this Class to assist with common queries.

For documentation of the Media Wiki API routes and endpoints, see the Media Wiki documentation.

class rswiki_wrapper.wiki.MediaWiki(game, user_agent='RS Wiki API Python Wrapper - Default', **kwargs)¶

This class is used to access the MediaWiki API for pulling information from the Wiki. An empty instance can be created for using the various helper methods built into this class, or the query can be made directly from this interface using the appropriate kwargs.

Parameters:

game (str, optional) – The game RSWiki should refer to. Valid options are 'osrs' or 'rs3'.
user_agent (str) – The user agent string to use in the query. Default is 'RS Wiki API Python Wrapper - Default'.

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

json¶

The raw JSON formatted response from the API

Type:: dict

content¶: The parsed content of the request. If created via the constructor method, it will be identical to the json content. If created via the built-in methods, it will be formatted to contain the requested data with minimal data wrangling required.

_clean_properties()¶: Clean the property keys in the content attribute by renaming them to more human-readable names.

_dirty_properties()¶: Revert the property keys in the content attribute to their original names.

ask(result_format: str = 'json', conditions: list[str] | None = None, printouts: list[str] | None = None, offset: str | None = None, **kwargs)¶

This method sends an ASK query to the MediaWiki API using the specified conditions and printouts parameters, and optional offset parameter. The result_format specifies the format in which the response is returned.

Parameters:

result_format (str, optional) – The format in which the response is returned. Default is 'json'.
conditions (list[str]) – The conditions to match in the ASK query.
printouts (list[str]) – The printouts (results) to provide from the ASK query.
offset (str, optional) – The offset in results. Typical ASK queries provide 50 results, so offset='50' will provide results 51-100 (or lower if there are less than 100 results).

Note

This route only updates the .json attribute due to the variety of possible printouts. To get the .content, first try the .get_ask_content() method which parses the conditions and printouts.

Examples

Example usage of the ASK query to find production JSON data for all items:

>>> query = MediaWiki('osrs', user_agent='My Project - me@example.com')
>>> query.ask(conditions=['Category:Items', 'Production JSON::+'], printouts=['Production JSON'])
>>> query.json['query']['results']['Abyssal bludgeon']['printouts']['Production JSON'][0]
'{"ticks":"","materials":[{"name":"Bludgeon axon","quantity":"1"},{"name":"Bludgeon claw","quantity":"1"},
{"name":"Bludgeon spine","quantity":"1"}],"facilities":"The Overseer","skills":[],"members":"Yes","output":
{"cost":11131623,"quantity":"1","name":"Abyssal bludgeon","image":
"[[File:Abyssal bludgeon.png|link=Abyssal bludgeon]]"}}'

Hint

If trying to access the Production JSON or Exchange JSON information, use the included ask_production and ask_exchange methods below, which make the result navigation much simpler.

ask_exchange(item: str | None = None, get_all: bool = False)¶

This method retrieves exchange data for the specified item or all items.

Parameters:

item (str, optional) – The item name to search Exchange Information. If no name is provided, all items with a valid Exchange JSON will be returned.
get_all (bool, optional) – To recursively search for all matching items, or only provide the first page of results, which by RSWiki convention is 50 results.

Warning

Unlike the ask_production method, a category can not be specified. This is because the Exchange JSON is actually formatted as [Exchange:Item]], and [[Exchange:Category:X]] is not a valid condition.

Returns:

None. Updates the .content attribute as follows. item is the name of the item provided in args. Resulting content format:

{
    'Exchange:Item' (str):
        [
            {
                'historical' : historical_info (bool),
                'id': ge_item_id (int),
                'lowalch': low_alch (int),
                'limit': ge_limit (int),
                'isalchable': alchable (bool),
                'value' : ge_value (int),
                'info': module_page (str),
                'name': item_name (str),
                'highalch': high_alch (int),
            },
            # A new dict for any other exchange pages with this name
        ]
    # A new key for each item name
}

Example

Example of getting Exchange JSON information for Cake:

>>> query = MediaWiki('osrs', user_agent='My Project - me@example.com')
>>> query.ask_exchange('Cake')
>>> query.content['Exchange:Cake'][0]['info']
'Module:Exchange/Cake'

Warning

Using get_all will recursively retrieve all results of the query. Retrieving all Exchange pages recursively will result in a long wait to retrieve the results. This is because the wrapper has a limit of 1 query/second when recursively following the results to reduce load on the API.

ask_production(item: str | None = None, get_all: bool = False)¶

Makes a query to the MediaWiki API to retrieve production data for a given item or category of items.

Parameters:

item (str, optional) – The item name to search Production Information. Can also be a Category 'Category:X'. If no name is provided, all items with a valid Production JSON will be returned.
get_all (bool, optional) – To recursively search for all matching items, or only provide the first page of results, which by RSWiki convention is 50 results.

Returns:

None. Updates the .content attribute as follows. item is the name of the item provided in args or all items matching the category selected. Resulting content format:

{
    item (str):
        [
            {
                'ticks' : ticks (str),
                'materials': [
                    {
                        'name': material_name (str),
                        'quantity': material_quantity (str)
                    }
                    # New dict for each material
                ],
                'facilities': facilities (str),
                'skills': [
                    {
                        'experience': experience_per (str),
                        'level': level_required (str),
                        'name': level_name (str),
                        'boostable': yes_no (str)
                    }
                    # New dict for each material
                ],
                'members': yes_no (str),
                'output': {
                    'cost': cost (int)
                    'quantity': quantity (str),
                    'name': name (str),
                    'image': img_link (str)
                }
            },
            # A new dict for each production method
        ]
    # A new key for each item name
}

Example

Example of getting Production JSON information for Cake:

>>> query = MediaWiki('osrs', user_agent='My Project - me@example.com')
>>> query.ask_production('Cake')
>>> query.content['Cake'][0]['skills']
[{'experience': '180', 'level': '40', 'name': 'Cooking', 'boostable': 'Yes'}]

Warning

Using get_all will recursively retrieve all results of the query. For some queries such as getting all production JSON information for all items, this results in a long wait to retrieve the results. This is because the wrapper has a limit of 1 query/second when recursively following the results to reduce load on the API.

browse(result_format: str = 'json', format_version: str = 'latest', **kwargs) → None¶

Use the SMWbrowse API endpoint to browse Semantic MediaWiki data. This helper assists with the smwbrowse action.

Parameters:

result_format (str, optional) – The format in which the response is returned. Default is `json'.
format_version (str, optional) – The version of the chosen format to use. Default is 'latest'
**kwargs – Additional keyword arguments to pass as params to the query.

Note

This route only updates the .json attribute due to the variety of possible printouts. To get the .content, custom parsing is required.

Hint

If trying to browse for properties of pages (Special:Browse) the browse_properties() method will simplify the parsing of json content.

browse_properties(item: str)¶

Retrieve property values for a given subject.

Parameters:: item (str) – The page name to search properties for.
Returns:: None. Creates the .content attribute as a dict with keys of each property and values of the value of each property.

Example

Example of getting all property information for Cake:

>>> query = MediaWiki('osrs', user_agent='My Project - me@example.com')
>>> query.browse_properties('Cake')
>>> query.content.keys()
dict_keys(['All_Image', 'All_Is_members_only', 'All_Item_ID', 'All_Weight', 'Cooking_experience',
'Cooking_level', 'Default_version', 'Is_boostable', 'Is_members_only', 'Production_JSON', 'Store_price_delta',
'Uses_facility', 'Uses_material', 'Uses_skill', 'Version_count', '_INST', '_MDAT', '_SKEY', '_SOBJ'])

# Cleaning the `_X` properties to human-readable values.
>>> query._clean_properties()
dict_keys(['All_Image', 'All_Is_members_only', 'All_Item_ID', 'All_Weight', 'Cooking_experience',
'Cooking_level', 'Default_version', 'Is_boostable', 'Is_members_only', 'Production_JSON', 'Store_price_delta',
'Uses_facility', 'Uses_material', 'Uses_skill', 'Version_count', 'Category', 'Modification Date', 'Name', 'Subobject'])

get_ask_content(conditions: list[str], printouts: list[str], get_all: bool = False) → None¶

A helper function to retrieve content from an ASK query in the MediaWiki API.

Parameters:

conditions (list[str]) – The conditions to match in the ASK query.
printouts (list[str]) – The printouts (results) to provide from the ASK query.
get_all (bool, optional) – Whether to retrieve all results from the ASK query recursively.

Warning

Using get_all will recursively retrieve all results of the query. For some queries such as getting all production JSON information for all items, this results in a long wait to retrieve the results. This is because the wrapper has a limit of 1 query/second when recursively following the results to reduce load on the API.

WikiQuery¶

This is the parent class for all queries to the various endpoints.

class rswiki_wrapper.wiki.WikiQuery(url: str | None = None, user_agent: str = 'RS Wiki API Python Wrapper - Default', **kwargs)¶

A class for querying the RS Wiki API. If no URL is provided, the constructor returns a WikiQuery object with a None type response object. The response can then be created using MediaWiki.update() or specific Child-class methods.

Parameters:

url (str, optional) – The URL of the API endpoint to query.
user_agent (str, optional) – The user agent string to use for the request. Default is 'RS Wiki API Python Wrapper - Default'.
**kwargs – Additional parameters to include in the query. See child classes for required kwargs.

headers¶

The headers sent with the request object. Created from user_agent

Type:: dict

response¶

The response object provided by the requests library.

Type:: Response

update(url, **kwargs)¶

Refresh the query with a new URL and additional parameters. Updates the self.response attribute.

Parameters:

url (str) – The URL of the API endpoint to query.
**kwargs – Additional parameters to include in the query. See child classes for required kwargs.