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
Parameter | Optional | Note |
---|---|---|
Player | No | The player name to lookup |
Mode | Yes | One of normal , ironman , hardcore , ultimate , seasonal , tournament . Defaults to normal . |
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
Parameter | Optional | Note |
---|---|---|
Skill | No | The skill name to lookup |
Mode | Yes | One of normal , ironman , hardcore , ultimate , seasonal , tournament . Defaults to normal |
Page | Yes | The page number to request. Defaults to 0 |
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
Parameter | Optional | Note |
---|---|---|
Activity | No | The activity name to lookup |
Mode | Yes | One of normal , ironman , hardcore , ultimate , seasonal , tournament . Defaults to normal |
Page | Yes | The page number to request. Defaults to 0 |
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
Parameter | Optional | Note |
---|---|---|
Player | No | The player to get display name for |
Mode | Yes | One of normal , ironman , hardcore , ultimate , seasonal , tournament . Defaults to normal |
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 thedata
propertyInvalidCsvError
- Parsing error, includes the raw csv in thedata
propertyInvalidPlayerError
- 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.
4 years ago