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.

---

$3

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:

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

Once you import it you can call the functions asynchronously:

`typescript
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:

`typescript
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:

$3

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

$3

| 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 |

$3

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

$3

| 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 |
| Doom of Mokhaiotl | doomOfMokhaiotl |
| 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 |
| Yama | yama |
| Zalcano | zalcano |
| Zulrah | zulrah |

What you'll get

getStats returns a player object that looks like this:

`typescript
{
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):

`typescript
[
{ 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:

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