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
Collections Logged	collectionsLogged

Points

Activity	Param
League Points	leaguePoints
Deadman Points	deadmanPoints

Bosses

Boss Name	Param
Abyssal Sire	abyssalSire
Alchemical Hydra	alchemicalHydra
Amoxliatl	amoxliatl
Araxxor	araxxor
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 Hueycoatl	hueycoatl
The Leviathan	leviathan
The Royal Titans	royalTitans
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: {},
    colosseumGlory: {},
    collectionsLogged: {},
    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'];