oldschool-api

A node.js-based wrapper for OSRS's hiscores API and Grand Exchange API. Forked from atjeff/Osrs-Wrapper.

Installation

With npm

$ npm install --save oldschool-api

With yarn

$ yarn add oldschool-api

Usage

Hiscores

createHiscoresInterface(axiosInstance)

Used to create an OSRS hiscores interface with a custom instance of Axios. Useful if you need to customize how you make HTTP requests. Returns an OSRS hiscores interface.

Example

const axios = require('axios');
const { hiscores: { createHiscoresInterface } } = require('oldschool-api');

const hiscoresInterface = createHiscoresInterface(axios.create());

createDefaultHiscoresInterface()

Used to create an OSRS hiscores interface with a default instance of Axios. Useful if you don't care about customizing how you make HTTP requests. Returns an OSRS hiscores interface.

Example

const { hiscores: { createDefaultHiscoresInterface } } = require('oldschool-api');

const hiscoresInterface = createDefaultHiscoresInterface();

hiscoresInterface.getPlayers([{ playerName, playerType }, ...])

Used to retrieve the stats and ranks for an array of players. Returns a promise containing an array of player stats and ranks.

Example

const {
  hiscores: {
    constants: { playerTypes },
    createDefaultHiscoresInterface,
  }
} = require('oldschool-api');

const hiscoresInterface = createDefaultHiscoresInterface();
const players = await hiscoresInterface.getPlayers([
  { name: 'FratRay', type: playerTypes.normal }
]);

console.log(players);

Output

[{
  name: 'FratRay',
  type: 'normal',
  overall: { rank: 320998, level: 1711, experience: 46233252 },
  attack: { rank: 475767, level: 80, experience: 2036974 },
  defence: { rank: 468494, level: 80, experience: 1986835 },
  strength: { rank: 656150, level: 82, experience: 2578010 },
  hitpoints: { rank: 669638, level: 82, experience: 2625101 },
  ranged: { rank: 828655, level: 77, experience: 1524857 },
  prayer: { rank: 560953, level: 70, experience: 738044 },
  magic: { rank: 689486, level: 78, experience: 1713947 },
  cooking: { rank: 156579, level: 99, experience: 13034517 },
  woodcutting: { rank: 201349, level: 82, experience: 2644653 },
  fletching: { rank: 175502, level: 90, experience: 5347428 },
  fishing: { rank: 274804, level: 80, experience: 2004485 },
  firemaking: { rank: 377529, level: 76, experience: 1388913 },
  crafting: { rank: 238602, level: 75, experience: 1305755 },
  smithing: { rank: 211295, level: 75, experience: 1234388 },
  mining: { rank: 658718, level: 63, experience: 383988 },
  herblore: { rank: 223866, level: 75, experience: 1306000 },
  agility: { rank: 598594, level: 64, experience: 442280 },
  thieving: { rank: 978324, level: 45, experience: 64662 },
  slayer: { rank: 408084, level: 77, experience: 1485284 },
  farming: { rank: 287433, level: 75, experience: 1211295 },
  runecrafting: { rank: 375327, level: 54, experience: 156341 },
  hunter: { rank: 387138, level: 67, experience: 569283 },
  construction: { rank: 387945, level: 65, experience: 450212 },
  leaguePoints: { rank: -1, score: -1 },
  bountyHunter: { rank: -1, score: -1 },
  bountyHunterRogue: { rank: -1, score: -1 },
  clueScrollOverall: { rank: 552188, score: 14 },
  clueScrollBeginner: { rank: -1, score: -1 },
  clueScrollEasy: { rank: 600130, score: 2 },
  clueScrollMedium: { rank: 380318, score: 7 },
  clueScrollHard: { rank: 416120, score: 5 },
  clueScrollElite: { rank: -1, score: -1 },
  clueScrollMaster: { rank: -1, score: -1 },
  lastManStanding: { rank: -1, score: -1 }
}]

hiscoresInterface.getRanks({ rankRange: { from, to }, playerType, entryType })

Used to retrieve the player rank information within a range of ranks for an account type and skill/minigame. Returns a promise containing an array of ranks.

Disclaimer: This is parsed from raw HTML on the hiscores page. This may break if Jagex significantly changes how the HTML on the page is structured.

Example

const {
  hiscores: {
    constants: {
      playerTypes,
      hiscoreEntryTypes,
    },
    createDefaultHiscoresInterface,
  }
} = require('oldschool-api');

const hiscoresInterface = createDefaultHiscoresInterface();
const ranks = await hiscoresInterface.getRanks({
  rankRange: { from: 1, to: 50 },
  playerType: playerTypes.seasonal,
  hiscoreEntryType: hiscoreEntryTypes.hunter,
});

console.log(ranks);

Output

[
  { rank: 1, name: 'S3n', score: 99, subscore: 200000000 },
  { rank: 2, name: 'moonfishes', score: 99, subscore: 152830038 },
  { rank: 3, name: 'MaintainRitm', score: 99, subscore: 101537571 },
  { rank: 4, name: 'Poll', score: 99, subscore: 100615065 },
  { rank: 5, name: 'Ewaz3', score: 99, subscore: 100572017 },
  { rank: 6, name: 'PancakeOSRS', score: 99, subscore: 100058195 },
  { rank: 7, name: 'Kacy', score: 99, subscore: 100054313 },
  { rank: 8, name: 'Foesum', score: 99, subscore: 100010172 },
  { rank: 9, name: 'Flaerewing', score: 99, subscore: 100003662 },
  { rank: 10, name: 'Hygera', score: 99, subscore: 100000911 },
  { rank: 11, name: 'Zara', score: 99, subscore: 100000514 },
  { rank: 12, name: 'Ashington', score: 99, subscore: 65355073 },
  { rank: 13, name: 'CardinalKnut', score: 99, subscore: 58654215 },
  { rank: 14, name: '45smith2345', score: 99, subscore: 57092002 },
  { rank: 15, name: 'Juniker', score: 99, subscore: 56403841 },
  { rank: 16, name: 'Yoshii', score: 99, subscore: 56099224 },
  { rank: 17, name: 'Tenhou', score: 99, subscore: 55212904 },
  { rank: 18, name: 'Titty�Doctor', score: 99, subscore: 53962263 },
  { rank: 19, name: 'OG�Hunter', score: 99, subscore: 53514468 },
  { rank: 20, name: 'Gohanuto', score: 99, subscore: 51052934 },
  { rank: 21, name: 'Trainer�Bad', score: 99, subscore: 50936316 },
  { rank: 22, name: 'Unid�Herbs', score: 99, subscore: 50513186 },
  { rank: 23, name: 'Repiphany', score: 99, subscore: 50400504 },
  { rank: 24, name: 'Erase tha', score: 99, subscore: 50280637 },
  { rank: 25, name: 'Rhomth', score: 99, subscore: 50164846 },
  { rank: 26, name: 'Boham', score: 99, subscore: 50092546 },
  { rank: 27, name: 'Thalarios', score: 99, subscore: 50087004 },
  { rank: 28, name: 'B�ingo', score: 99, subscore: 50082744 },
  { rank: 29, name: 'More�AFK', score: 99, subscore: 50081640 },
  { rank: 30, name: 'Cream�City', score: 99, subscore: 50080012 },
  { rank: 31, name: 'RageFabe', score: 99, subscore: 50052230 },
  { rank: 32, name: 'Silcooper', score: 99, subscore: 50033771 },
  { rank: 33, name: 'Trench', score: 99, subscore: 50027737 },
  { rank: 34, name: 'Plastikos', score: 99, subscore: 50023169 },
  { rank: 35, name: 'Turb0Spud', score: 99, subscore: 50021684 },
  { rank: 36, name: 'Jacc', score: 99, subscore: 50019224 },
  { rank: 37, name: 'Godzixe', score: 99, subscore: 50018662 },
  { rank: 38, name: 'Xilsy', score: 99, subscore: 50015965 },
  { rank: 39, name: 'Elyrion', score: 99, subscore: 50015296 },
  { rank: 40, name: 'RUSSlA', score: 99, subscore: 50014099 },
  { rank: 41, name: 'Sir�Ton4', score: 99, subscore: 50012328 },
  { rank: 42, name: 'Ultimate�SSB', score: 99, subscore: 50010018 },
  { rank: 43, name: 'DaddyNarut0', score: 99, subscore: 50009821 },
  { rank: 44, name: 'Br3ttD0g59', score: 99, subscore: 50009589 },
  { rank: 45, name: 'Nubslie', score: 99, subscore: 50009228 },
  { rank: 46, name: 'Burnt1obster', score: 99, subscore: 50008864 },
  { rank: 47, name: 'Boriz', score: 99, subscore: 50008649 },
  { rank: 48, name: 'wzrddddd', score: 99, subscore: 50008242 },
  { rank: 49, name: 'Open�GL', score: 99, subscore: 50007560 },
  { rank: 50, name: '4949', score: 99, subscore: 50005984 }
]

constants.hiscoreEntryTypes

A map of different hiscore entry types like fishing, total clue scrolls complete, and overall level. Contains the name of the entry, the category (skill vs. minigame), and the table index of the entry.

Example

const {
  hiscores: { constants: { hiscoreEntryTypes } },
} = require('oldschool-api');

console.log(hiscoreEntryTypes);

Output

{
  /* ... */
  fishing: {
    name: 'fishing',
    category: 0,
    table: 11,
  },
  /* ... */
  clueScrollsOverall: {
    name: 'clueScrollsOverall',
    category: 1,
    table: 3,
  },
  /* ... */
}

constants.hiscoreSkillEntryTypeOrder

An array of hiscore skill entries the order in which they're given by the hiscores API.

Example

const {
  hiscores: { constants: { hiscoreSkillEntryTypeOrder } },
} = require('oldschool-api');

console.log(hiscoreSkillEntryTypeOrder);

Output

[
  { name: 'overall', category: 0, table: 0 },
  { name: 'attack', category: 0, table: 1 },
  /* ... */
  { name: 'construction': catrgory: 0, table: 23 },
]

constants.hiscoreMinigameEntryTypeOrder

An array of hiscore minigame entries the order in which they're given by the hiscores API.

Example

const {
  hiscores: { constants: { hiscoreMinigameEntryTypeOrder } },
} = require('oldschool-api');

console.log(hiscoreMinigameEntryTypeOrder);

Output

[
  { name: 'leaguePoints', category: 1, table: 0 },
  { name: 'bountyHunter', category: 1, table: 1 },
  /* ... */
  { name: 'lastManStanding': catrgory: 1, table: 23 },
]

constants.playerTypes

A map of account/players types for use with the hiscores API.

Example

const {
  hiscores: { constants: { playerTypes } },
} = require('oldschool-api');

console.log(playerTypes);

Output

{
  normal: 'normal',
  ironman: 'ironman',
  ultimateIronman: 'ultimate',
  hardcoreIronman: 'hardcore_ironman',
  deadman: 'deadman',
  seasonal: 'seasonal',
}

Grand Exchange

createGrandExchangeInterface(axiosInstance)

Used to create an OSRS Grand Exchange interface with a custom instance of Axios. Useful if you need to customize how you make HTTP requests. Returns an OSRS Grand Exchange interface.

Example

const axios = require('axios');
const { grandExchange: { createGrandExchangeInterface } } = require('oldschool-api');

const grandExchangeInterface = createGrandExchangeInterface(axios.create());

createDefaultGrandExchangeInterface()

Used to create an OSRS Grand Exchange interface with a default instance of Axios. Useful if you don't care about customizing how you make HTTP requests. Returns an OSRS Grand Exchange interface.

Example

const { grandExchange: { createDefaultGrandExchangeInterface } } = require('oldschool-api');

const grandExchangeInterface = createDefaultGrandExchangeInterface();

grandExchangeInterface.getItem(itemId)

Used to retrieve an item's Grand Exchange details. Returns an item's Grand Exchange details.

Example

const { grandExchange: { createDefaultGrandExchangeInterface } } = require('oldschool-api');

const grandExchangeInterface = createDefaultGrandExchangeInterface();
const item = await grandExchange.getItem(2);

console.log(item);

Output

{
  item: {
    icon: 'http://services.runescape.com/m=itemdb_oldschool/1522058952475_obj_sprite.gif?id=2',
    icon_large: 'http://services.runescape.com/m=itemdb_oldschool/1522058952475_obj_big.gif?id=2',
    id: 2,
    type: 'Default',
    typeIcon: 'http://www.runescape.com/img/categories/Default',
    name: 'Cannonball',
    description: 'Ammo for the Dwarf Cannon.',
    current: { trend: 'neutral', price: 166 },
    today: { trend: 'positive', price: '+2' },
    members: 'true',
    day30: { trend: 'negative', change: '-8.0%' },
    day90: { trend: 'negative', change: '-11.0%' },
    day180: { trend: 'negative', change: '-8.0%' },
  }
}

grandExchangeInterface.getGraph(itemId)

Used to retrieve an item's Grand Exchange price data for the last six months. Returns an item's Grand Exchange price data for the last six months.

Example

const { grandExchange: { createDefaultGrandExchangeInterface } } = require('oldschool-api');

const grandExchangeInterface = createDefaultGrandExchangeInterface();
const graph = await grandExchange.getGraph(2);

console.log(graph);

Output

{
  daily: {
    1506729600000: 186,
    // ...
    1522195200000: 166
  },
  average: {
    1506729600000: 185,
    // ...
    1522195200000: 169
  }
}

Future Improvements

1. Addition of utility functions for doing things like flattening player hiscore entries into an array rather than map
2. getRanks currently also retrieves ranks slightly outside of the desired range
3. Integration tests to check if schemas are changed
4. Re-written in TypeScript