OSRS Exchange

A Promise based Old School RuneScape grand exchange API.

OSRS Exchange goal is to streamline the process of programmatically interacting with the Old School RuneScape grand exchange. This is done by having excellent configuration to support a wide range of use-cases and using JSON friendly objects as return types.

We provide simple methods for:

• Get item with detailed price by id or name
• Get price history of item by id or name
• Get item pages by alpha and page number

TypeScript is fully supported with definitions and custom types.

Installation

$ npm install osrs-exchange

Usage

Import

Currently ES6 import is being used by default. This means if you are using CommonJS you need to import using the following syntax:

const Exchange = require('osrs-exchange').default;

Configuration

We support optional custom configuration for the HTTP requests being performed by the library. Default values will be used if no config is provided when initializing the Exchange object.

const config = {
  // `userAgent` specifies which user agent to send in the header of the request
  userAgent: 'osrs-exchange',

  // `timeout` specifies the number of milliseconds before the request times out.
  // If the request takes longer than `timeout`, the request is aborted.
  timeout: 1000, // default is `0` (no timeout)

  // `proxy` defines the hostname and port of the proxy server.
  // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
  // supplies credentials. This will set an `Proxy-Authorization` header.
  proxy: {
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'bobross',
      password: 'happy11accidents',
    },
  },
};

getItemById

Gathers item details from the grand exchange with scraped prices for accuracy.

Parameter	Required	Note
Id	Yes	The item id to fetch

Usage

import Exchange from 'osrs-exchange';

const exchange = new Exchange({ timeout: 1000 }); // optional config

exchange
  .getItemById(4151)
  .then(res => console.info(res))
  .catch(err => console.error(err));

Response

{
  id: 4151,
  name: 'Abyssal whip',
  description: 'A weapon from the abyss.',
  icon: 'http://services.runescape.com/m=itemdb_oldschool/1582802986184_obj_big.gif?id=4151',
  members: true,
  price: {
    current: 2394089,
    change: { today: 2635, day30: -206892, day90: -276497, day180: -101868 }
  }
}

getItemByName

Gathers item details from the grand exchange with scraped prices for accuracy.

Parameter	Required	Note
Name	Yes	A string containing the ItemName

Usage

import Exchange from 'osrs-exchange';

const exchange = new Exchange(); // optional config

exchange
  .getItemByName('abyssal whip')
  .then(res => console.info(res))
  .catch(err => console.error(err));

Response

Same response as getItemById.

getPriceHistoryById

Returns the daily and average price history of an item. The entires are represented by ISO8601 keys with the related price as the value.

Note: This method can not be used from a browser due to Cross-Origin Resource Sharing being disabled on the Old School RuneScape exchange API.

Parameter	Required	Note
Id	Yes	The item id to fetch

Usage

import Exchange from 'osrs-exchange';

const exchange = new Exchange(); // optional config

exchange
  .getPriceHistoryById(4151)
  .then(res => console.info(res))
  .catch(err => console.error(err));

Response

{
  daily: {
    '2020-02-29T00:00:00.000Z': 2391454,
    '2020-03-01T00:00:00.000Z': 2394089,
    ...
  },
  average: {
    '2020-02-29T00:00:00.000Z': 2463351,
    '2020-03-01T00:00:00.000Z': 2455244,
    ...
  }
}

getPriceHistoryByName

Returns the daily and average price history of an item. The entires are represented by ISO8601 keys with the related price as the value.

Note: This method can not be used from a browser due to Cross-Origin Resource Sharing being disabled on the Old School RuneScape exchange API.

Parameter	Required	Note
Name	Yes	A string containing the ItemName

Usage

import Exchange from 'osrs-exchange';

const exchange = new Exchange(); // optional config

exchange
  .getPriceHistoryByName('abyssal whip')
  .then(res => console.info(res))
  .catch(err => console.error(err));

Response

Same response as getPriceHistoryById.

getItemPage

Fetches up to 12 items that start with alpha character on the given page.

Note: This method can not be used from a browser due to Cross-Origin Resource Sharing being disabled on the Old School RuneScape exchange API.

Parameter	Required	Note
Alpha	Yes	A character a-z (first letter of the item name)
Page	No	The page number to get (defaults to 1)

Usage

import Exchange from 'osrs-exchange';

const exchange = new Exchange(); // optional config

exchange
  .getItemPage('a', 5)
  .then(res => console.info(res))
  .catch(err => console.error(err));

Response

[
  {
    id: 10392,
    name: 'A powdered wig',
    description: 'A big do about nothing.',
    members: true,
    icon: 'http://services.runescape.com/m=itemdb_oldschool/1583157682291_obj_big.gif?id=10392'
  },
  {
    id: 13263,
    name: 'Abyssal bludgeon',
    description: 'Elements of deceased Abyssal Sires have been fused together.',
    members: true,
    icon: 'http://services.runescape.com/m=itemdb_oldschool/1583157682291_obj_big.gif?id=13263'
  },
  ...
]

Types

See the TYPES file for details.

Contributing

See the CONTRIBUTING file for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.