OSRS Hiscores
A Promise based Old School RuneScape hiscores API.
OSRS Hiscores goal is to streamline the process of programmatically interacting with the Old School RuneScape hiscores. This is done by having excellent configuration to support a wide range of use-cases and using JSON friendly objects as return types.
We provide simple methods for:
- Lookup: Individual player
- Lookup: Skill table page
- Lookup: Activity table page
- Parse: Display name format
TypeScript is fully supported with definitions and custom types.
Installation
$ npm install osrs-hiscores
Usage
Import
Currently ES6 import is being used by default. This means if you are using CommonJS you need to import using the following syntax:
const Hiscores = require('osrs-hiscores').default;
Configuration
We support optional custom configuration for the HTTP requests being performed by the library. Default values will be used if no config is provided when initializing the Hiscores
object.
const config = {
// `userAgent` specifies which user agent to send in the header of the request
userAgent: 'osrs-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',
},
},
};
getStats
Performs a hiscore lookup of the player name.
Note: This method can not be used from a browser due to Cross-Origin Resource Sharing
being disabled on the Old School RuneScape hiscores API.
Parameter | Required | Note |
---|---|---|
Player | Yes | The player name to lookup |
Mode | No | The mode (defaults to normal ) |
Usage
import Hiscores from 'osrs-hiscores';
const hiscores = new Hiscores({ timeout: 6000 }); // provide config if needed
hiscores
.getStats('zezima')
.then(res => console.log(res))
.catch(err => console.error(err));
Response
{
skills: {
overall: { rank: 1234, level: 1234, experience: 1234 },
attack: { rank: 1234, level: 1234, experience: 1234 },
...
},
clues: {
all: { rank: 453, score: 12345 },
beginner: { rank: 52356, score: 2 },
...
},
bosses: {
kingBlackDragon: { rank: 1, score: 11 },
theatreOfBlood: { rank: 654, score: 86 },
...
},
bountyHunter: {
hunter: { rank: 567, score: 3456 },
rogue: { rank: -1, score: -1 }
},
leaguePoints: { rank: 4321, score: 2 },
lastManStanding: { rank: 234, score: 235 }
}
getSkillPage
Performs a skill page lookup.
Parameter | Required | Note |
---|---|---|
Skill | Yes | The skill to lookup |
Mode | No | The mode (defaults to normal ) |
Page | No | The page number to request (defaults to 0 ) |
Usage
import Hiscores from 'osrs-hiscores';
const hiscores = new Hiscores(); // provide config if needed
hiscores
.getSkillPage('runecraft')
.then(res => console.log(res))
.catch(err => console.error(err));
Response
A list representing the page table of the requested skill.
[
{ rank: 1, level: 4321, experience: 4321, name: "zezima" },
{ rank: 2, level: 1234, experience: 1234, name: "lynx titan" },
...
]
Note: The dead
property is only included if mode
is hardcore
.
getActivityPage
Performs an activity page lookup.
Parameter | Required | Note |
---|---|---|
Activity | Yes | The activity to lookup |
Mode | No | The mode (defaults to normal ) |
Page | No | The page number to request (defaults to 0 ) |
Usage
import Hiscores from 'osrs-hiscores';
const hiscores = new Hiscores(); // provide config if needed
hiscores
.getActivityPage('lastManStanding', 'hardcore')
.then(res => console.log(res))
.catch(err => console.error(err));
Response
A list representing the page table of the requested skill.
[
{ rank: 1, score: 4321, name: "bob", dead: true },
{ rank: 2, score: 1234, name: "ross", dead: false },
...
]
Note: The dead
property is only included if mode
is hardcore
.
getDisplayName
Performs a lookup to find the formatted display name of the player.
Parameter | Required | Note |
---|---|---|
Player | Yes | The player name to lookup |
Mode | No | The mode (defaults to normal ) |
Usage
import Hiscores from 'osrs-hiscores';
const hiscores = new Hiscores(); // provide config if needed
hiscores
.getDisplayName('zezima')
.then(res => console.log(res))
.catch(err => console.error(err));
Response
{
format: 'Zezima';
}
Types
See the TYPES file for details.
Contributing
See the CONTRIBUTING file for details.
License
This project is licensed under the MIT License - see the LICENSE file for details.