osrs-json-hiscores v2.18.0

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:

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

Minigames

Points

Bosses

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'];