osrslogs-hiscores v1.0.0

OSRS Logs Hiscores

OSRS Logs Hiscores is a wrapper for the official Old School RuneScape hiscores API. The official API is lacking and returns a csv which is difficult to work with. This wrapper solves that problem by converting all responses to json. It also provides methods for interacting with the hiscore tables through API calls.

Promises, Async/Await are fully supported.

TypeScript

OSRS Logs Hiscores includes TypeScript support with definitions and custom types.

How to use

CORS

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 Logs Hiscores, should be installed and ran on the server side.

Installation

$ npm install osrslogs-hiscores

Import

// ES5 syntax
const Hiscores = require('osrslogs-hiscores');

// ES6 syntax
import Hiscores from 'osrslogs-hiscores';

Config

The config itself and all properties in the config are optional. Default values will be used if no config is provided.

const config = {
  // `userAgent` specifies which user agent to send in the header of the request
  userAgent: 'osrslogs-hiscores',

  // `timeout` specifies the number of milliseconds before the request times out.
  // If the request takes longer than `timeout`, the request is aborted.
  timeout: 1000, // default is `0` (no timeout)

  // `proxy` defines the hostname and port of the proxy server.
  // `auth` indicates that HTTP Basic auth should be used to connect to the proxy, and
  // supplies credentials. This will set an `Proxy-Authorization` header.
  proxy: {
    host: '127.0.0.1',
    port: 9000,
    auth: {
      username: 'bobross',
      password: 'happy11accidents',
    },
  },
};

Creating an instance

All methods are exposed through the hiscores instance. Config is optional.

const hiscores = new Hiscores({
  timeout: 1000
});

Method: getStats

Example

try {
  const stats: Stats = await hiscores.getStats('zezima');
  console.info(stats.skills.overall.rank);
} catch (err) {
  console.info(err.data) // contains the raw response from hiscores
}

Method: getSkillPage

Example

try {
  const skillRows: PlayerSkillRow[] = await hiscores.getSkillPage('cooking', undefined, 42);
  console.info(skillRows.length); // 1-25
  console.info(skillRows[0].rank);
} catch (err) {
  console.info(err.data) // contains the raw response from hiscores
}

Method: getActivityPage

Example

try {
  const activityRows: PlayerActivityRow[] = await hiscores.getActivityPage('nightmare');
  console.info(activityRows.length);
  console.info(activityRows[0].score);
} catch (err) {
  console.info(err.data) // contains the raw response from hiscores
}

Method: getDisplayName

try {
  const displayName: string = await hiscores.getDisplayName('bob ross', 'hardcore');
  console.info(displayName); // Bob Ross
} catch (err) {
  console.info(err.message);
}

Response structure

Player stats

{
  "skills": {
    "overall": {
      "rank": 1234,
      "level": 1234,
      "experience": 1234
    },
    "attack": {
      "rank": 1234,
      "level": 1234,
      "experience": 1234
    },
    ...
  },
  "leaguePoints": {
    "rank": 1234,
    "score": 1234
  },
  "bountyHunter": {
    "hunter": {
      "rank": 1234,
      "score": 1234
    },
    "rogue": {
      "rank": 1234,
      "score": 1234
    }
  },
  "clues": {
    "easy": {
      "rank": 1234,
      "score": 1234
    }, 
    "beginner": {
      "rank": 1234,
      "score": 1234
    }
    ...
  },
  "lastManStanding": {
    "rank": 1234,
    "score": 1234
  },
  "bosses": {
    "kingBlackDragon": {
      "rank": 1234,
      "score": 1234
    },
    "theatreOfBlood": {
      "rank": 1234,
      "score": 1234
    },
    ...
  }
}

Hiscore skill page

The dead property is only included on hardcore game mode lookups.

[
  {"rank": 1, "level": 4321, "experience": 4321, "name": "zezima"},
  {"rank": 2, "level": 1234, "experience": 1234, "name": "lynx titan"},
  ...
]

Hiscore activity page

The dead property is only included on hardcore game mode lookups.

[
  {"rank": 1, "score": 4321, "name": "bob", "dead": true},
  {"rank": 2, "score": 1234, "name": "ross", "dead": false},
  ...
]

Errors

• NotFoundError - Player not found on hiscores (status: 404)
• HttpError - Unexpected error or resposne from hiscores (status: 500)
• ServiceUnavailableError - Hiscores are unavailable (status: 503)
• InvalidHtmlError - Parsing error, includes the raw html in the data property
• InvalidCsvError - Parsing error, includes the raw csv in the data property
• InvalidPlayerError - Validation error for invalid player name

Versioning

We follow Semver for versioning. Due to the nature of interacting with a 3rd party website and API, any version may stop working properly. In that case update to @"<next-major.0.0" to get it working again. We will always make sure the latest of each major release is compatible with the hiscores.

License

This project is licensed under the MIT License - see the LICENSE file for details.