michaelbull / rs-api

An open-source implementation of a web-service client, written in Java, that allows interaction with the various APIs available for the popular MMORPG; RuneScape.

RuneScape API

rs-api is an open-source implementation of a web-service client, written in Java, that allows interaction with the various APIs available for the popular MMORPG; RuneScape.

Javadoc is available here.

Installation

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    compile 'com.github.michaelbull:rs-api:1.1.3'
}

Usage

The implementation offers functionality to interact with the following three public web-services:

• Bestiary
• Grand Exchange
• Hiscores

CSV and JSON results are parsed by the API and returned as Java Objects.

To start using rs-api, simply instantiate a HTTP based RuneScapeAPI class as follows:

RuneScapeAPI api = RuneScapeAPI.createHttp();

Note: The API can run using a HttpClient on the live RuneScape web-service, or a user supplied Client (e.g. a FakeClient for mocked unit testing).

At which point you may now access and query the Bestiary, GrandExchange, and Hiscores API objects:

Bestiary bestiary = api.bestiary();
GrandExchange grandExchange = api.grandExchange();
Hiscores hiscores = api.hiscores();

Examples

Search in Bestiary

The Bestiary API facilitates searching for a beast given a number of search filters (e.g. name, weakness, Slayer category).

Numerous filters can be applied to the Search by chaining them together, and are lazily evaluated when calling the terminal results method.

Map<Integer, String> beasts = bestiary.search()
	.filterByNameTerms("dragon")
	.filterByArea("Taverley Dungeon")
	.filterByLevel(100, 140)
	.results();

System.out.println("Results:");
for (Map.Entry<Integer, String> entry : beasts.entrySet()) {
	System.out.println("\t[" + String.format("%04d", entry.getKey()) + "] " + entry.getValue());
}

Outputs:

Results:
	[0054] Black dragon (100)
	[4673] Black dragon (100)

Item Price on Day

Calling the graphingData method with an Item's ID as the parameter (e.g. 4151 for an Abyssal whip) in the GrandExchange API will return the price information that may be used for graphical representation of an Item's price history.

Optional<GraphingData> optional = grandExchange.graphingData(4151);

optional.ifPresent(graphingData -> {
	LocalDate christmas = LocalDate.of(2014, Month.DECEMBER, 25);
	System.out.println("Daily price on Christmas 2014: " + graphingData.getDailyValue(christmas).get());
});

Outputs:

Daily price on Christmas 2014: 117549

Player Hiscore Rank

Calling the playerInformation method with a Player's name as a parameter (e.g. Drumgun) and a Hiscore Table as a parameter (e.g. Table.DEFAULT) in the Hiscores API will return the hiscore information for the Player, including Skill levels and Activity ranks.

Optional<Player> optional = hiscores.playerInformation("Drumgun", Table.DEFAULT);

optional.ifPresent(player -> System.out.println("Overall rank: " + player.getSkills().get("Overall")));

Outputs:

Overall rank: Skill{rank=1, level=2595, experience=5200000000}

Clan Information

Calling the clanInformation method with a clan's name (e.g. Sapphite Knights) as the parameter in the Hiscores API will return an ImmutableList of ClanMates.

List<ClanMate> clanMates = hiscores.clanInformation("Sapphite Knights");

System.out.println("Clan Mates:");
clanMates.forEach(System.out::println);

Outputs:

Clan Mates:
ClanMate{name=Rosaline, rank=Owner, experience=463143387, kills=0}
ClanMate{name=Corp Sloter, rank=Deputy Owner, experience=678318180, kills=54}
ClanMate{name=GorgeousBrat, rank=Deputy Owner, experience=166603367, kills=0}
ClanMate{name=Chris Return, rank=Overseer, experience=306089480, kills=0}
ClanMate{name=Sauf, rank=Overseer, experience=346299506, kills=3}
...

Building

Gradle is used as the build system. The Gradle Wrapper is included in the distribution and as such, installation of Gradle by the user is not required.

Run gradlew in the project's root directory to build the application and run the unit tests.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

This project is available under the terms of the ISC license. See the LICENSE file for the copyright information and licensing terms.