OSRS .json Hiscores

The Old School RuneScape API wrapper that does more!

What it does

The official hiscores API for Old School RuneScape (OSRS) can return CSV or a simple JSON array. This wrapper converts the hiscores data into a more usable JSON object and provides extra information about the given player. By comparing player info it infers the player's game mode, as well as any previous modes (de-ultimated, de-ironed and/or died as a hardcore ironman).

Additional functions are provided that screen-scrape the OSRS leaderboards and return a list of players as json. Also simple utility functions are provided to fetch the raw responses from Jagex's APIs, if desired.

osrs-json-hiscores has TypeScript support, with full definitions for all functions and custom data types.

⚠ Disclaimer ⚠

Jagex does not provide Access-Control-Allow-Origin headers in their responses. This means that CORS will block all browser requests to their hiscores API. In order to get around this, osrs-json-hiscores needs to be installed on the server side and exposed to the front end via a simple API. Here is an example of this in use: codesandbox.io/s/osrs-json-hiscores-demo

TLDR: You cannot use this library directly in your client side app e.g. React or Vue, you must set up a server which uses this lib internally and have your client fetch data from your server.

Installation

With npm:

$ npm install osrs-json-hiscores

With Yarn:

$ yarn add osrs-json-hiscores

How to use

Install the package and then import it into your project:

import { getStatsByGamemode, getSkillPage } from 'osrs-json-hiscores';

Once you import it you can call the functions asynchronously:

const stats = await getStatsByGamemode('Lynx Titan');
const topPage = await getSkillPage('overall');

getStats will return a full player object with gamemode.
getStatsByGameMode will return a stats object and accepts a gamemode parameter:

| Game mode | Param | | ---------------- | :----------: | | Regular | main | | Ironman | ironman | | Hardcore Ironman | hardcore | | Ultimate Ironman | ultimate | | Deadman Mode | deadman | | Tournament | tournament | | Leagues | seasonal |

getSkillPage and getActivityPage require a skill / activity and optionally a gamemode and page:

getSkillPage('attack', 'main', 1)
  .then((res) => console.log(res))
  .catch((err) => console.error(err));

Activities consist of all levels of clue scrolls as well as minigames and bosses:

Clue Scrolls

| Type | Param | | -------- | :-------------: | | All | allClues | | Beginner | beginnerClues | | Easy | easyClues | | Medium | mediumClues | | Hard | hardClues | | Elite | eliteClues | | Master | masterClues |

Minigames

| Minigame | Param | | ------------------------------- | :---------------: | | Bounty Hunter (Legacy - Rogue) | rogueBH | | Bounty Hunter (Legacy - Hunter) | hunterBH | | Bounty Hunter (Rogue) | rogueBHV2 | | Bounty Hunter (Hunter) | hunterBHV2 | | LMS - Rank | lastManStanding | | PvP Arena - Rank | pvpArena | | Soul Wars Zeal | soulWarsZeal | | Rifts closed | riftsClosed | | Colosseum Glory | colosseumGlory |

Points

| Activity | Param | | -------------- | :-------------: | | League Points | leaguePoints | | Deadman Points | deadmanPoints |

Bosses

| Boss Name | Param | | --------------------------------- | :----------------------------: | | Abyssal Sire | abyssalSire | | Alchemical Hydra | alchemicalHydra | | Artio | artio | | Barrows Chests | barrows | | Bryophyta | bryophyta | | Callisto | callisto | | Calvar'ion | calvarion | | Cerberus | cerberus | | Chambers Of Xeric | chambersOfXeric | | Chambers Of Xeric: Challenge Mode | chambersOfXericChallengeMode | | Chaos Elemental | chaosElemental | | Chaos Fanatic | chaosFanatic | | Commander Zilyana | commanderZilyana | | Corporeal Beast | corporealBeast | | Crazy Archaeologist | crazyArchaeologist | | Dagannoth Prime | dagannothPrime | | Dagannoth Rex | dagannothRex | | Dagannoth Supreme | dagannothSupreme | | Deranged Archaeologist | derangedArchaeologist | | Duke Sucellus | dukeSucellus | | General Graardor | generalGraardor | | Giant Mole | giantMole | | Grotesque Guardians | grotesqueGuardians | | Hespori | hespori | | Kalphite Queen | kalphiteQueen | | King Black Dragon | kingBlackDragon | | Kraken | kraken | | Kreearra | kreeArra | | K'ril Tsutsaroth | krilTsutsaroth | | Lunar Chests | lunarChests | | Mimic | mimic | | Nex | nex | | Nightmare | nightmare | | Phosani's Nightmare | phosanisNightmare | | Obor | obor | | Phantom Muspah | phantomMuspah | | Sarachnis | sarachnis | | Scorpia | scorpia | | Scurrius | scurrius | | Skotizo | skotizo | | Sol Heredit | solHeredit | | Spindel | spindel | | Tempoross | tempoross | | The Gauntlet | gauntlet | | The Corrupted Gauntlet | corruptedGauntlet | | The Leviathan | leviathan | | The Whisperer | whisperer | | Theatre Of Blood | theatreOfBlood | | Theatre Of Blood: Hard Mode | theatreOfBloodHardMode | | Thermonuclear Smoke Devil | thermonuclearSmokeDevil | | Tombs of Amascut | tombsOfAmascut | | Tombs of Amascut: Expert Mode | tombsOfAmascutExpertMode | | TzKal-Zuk | tzKalZuk | | TzTok-Jad | tzTokJad | | Vardorvis | vardorvis | | Venenatis | venenatis | | Vetion | vetion | | Vorkath | vorkath | | Wintertodt | wintertodt | | Zalcano | zalcano | | Zulrah | zulrah |

What you'll get

getStats returns a player object that looks like this:

{
  name: 'Lynx Titan',
  mode: 'main',
  dead: false,
  deulted: false,
  deironed: false,
  main: {
    skills: {
      overall: {rank: 1, level: 2277, xp: 4600000000},
      attack: {},
      defence: {},
      // ...
    },
    clues: {},
    leaguePoints: {},
    bountyHunter: {},
    lastManStanding: {},
    pvpArena: {},
    soulWarsZeal: {},
    riftsClosed: {},
    bosses: {}
  }
}

getSkillPage returns and array of 25 players (This represents a page on the hiscores):

[
  { rank: 1, name: 'Lynx Titan', level: 2277, xp: 4600000000, dead: false },
  {},
  {}
  // ...
];

Helpful Extras

Get the properly formatted name of any skill, boss, clue or other activity:

// kril === "K'ril Tsutsaroth"
const kril = FORMATTED_BOSS_NAMES['krilTsutsaroth'];