The purpose of this library is to provide simple access to the different APIs of the game Path of Exile by Grinding Gear Games. Data can be requested with simple method calls and is returned as fully typed class objects. The library was built upon the previous work of klayveR and his library poe-api-wrappers. Unfortunately, poe-api-wrappers is no longer maintained, outdated, and doesn't provide access to the OAuth2 API. Hence, this library was created.
Note: This product isn't affiliated with or endorsed by Grinding Gear Games in any way.
The key objectives of this library are:
- Provide simplified access to the official PoE APIs. These include the Public API, the OAuth API and the Session API using the POESESSID cookie.
- Provide simplified access to the poe.ninja API for fetching economy data.
- Provide the data fetched from the APIs as class objects using class-transformer enhanced with methods for ease of use.
Install the latest stable version of this library:
npm install --save poe-api-ts
import { PathOfExile } from "poe-api-ts";
Before making requests to the official API, you should set your user agent, as requested by GGG here.
PathOfExile.Settings.userAgent = "my-awesome-tool-name, contact@me.com";
These settings are sufficient in order to use the PoE Public API & poe.ninja. However, in order to use the Session and the OAuth API further setup is required.
In order to use the PoE Session API, the POESESSID needs to be set.
PathOfExile.Settings.sessionId = "somePOESESSID";
The PoE OAuth API uses OAuth2.0 for authorization. The official documentation by GGG can be found here. The endpoints in the PoE OAuth API require the token to be set and the required scope.
In order to access endpoints which are related to an account, the token obtained by the Authorization Code Grant needs to be set
PathOfExile.Settings.authorizationToken = "someAuthorizationToken";
In order to access endpoints which are not related to an account, the token obtained by the Client Credentials Grant needs to be set
PathOfExile.Settings.serviceToken = "someServiceToken";
let chunk = await PathOfExile.PublicAPI.PublicStashes.getChunk();
for (let index = 0; index < 9; index++) {
console.log(`This chunk as ${chunk.stashes.length} stashes.`);
chunk = await chunk.getNext();
}
// Get the ladder with the first 200 entries
const ladder = await PathOfExile.PublicAPI.Ladders.get("Standard", { limit: 200 });
// Request the remaining entries in chunks of 200 and append them to the current ladder object
// until there are no entries left
while ((await ladder.getNextEntries(true)) != null) {
console.log(`Current entries: ${ladder.entries.length}`);
}
// Filter by online players
const online = ladder.filterBy("online", true);
console.log(`${online.length}/${ladder.total} players are currently online.`);
const query: SearchQueryContainer = {
query: {
status: { option: "online" },
name: "Shavronne's Wrappings",
type: "Occultist's Vestment",
},
sort: { price: "asc" },
};
const search = await PathOfExile.PublicAPI.Trade.search("Standard", query);
const results = await search.getNextItems(10);
if (results != null) {
for (const result of results) {
const price = result.listing.price;
const name = result.item.name;
const seller = result.listing.account.name;
console.log(`Item '${name}' is being sold for ${price.amount} ${price.currency} by ${seller}`);
}
}
const accountName = "moepmoep12";
const charName = "CratoLsArch";
const char = await PathOfExile.PublicAPI.Characters.getByName(accountName, charName);
console.log(
`The character is level ${char.level} and has ${char.inventory.length} items in its inventory.`
);
// Update the inventory after some event happened, e.g. hideout entered
await char.updateInventory();
console.log(`The character has now ${char.inventory.length} items in its inventory.`);
These examples require the POESESSID to be set in the Settings.
// Get an overview of the stash with all tabs, excluding the items
const stash = await PathOfExile.SessionAPI.Stashes.getStash("myAccount", "Standard");
console.log(`The stash has ${stash.numTabs} tabs.`);
const stashTab = stash.tabs[0];
console.log(`The color of the stash tab is ${stashTab.Color}`);
// Get the items inside the stash tab
await stashTab.update();
console.log(`The stash tab '${stashTab.name}' contains ${stashTab.items?.length} items;`);
let chunk = await PathOfExile.PublicAPI.PublicStashes.getChunk();
for (let index = 0; index < 9; index++) {
console.log(`This chunk as ${chunk.stashes.length} stashes.`);
chunk = await chunk.getNext();
}
// Get an overview of the stash, exlcuding items inside the folders
const stash = await PathOfExile.OAuthAPI.Stashes.getStash("Standard");
// Find the first folder with children
const stashTabFolder = stash.tabs.find(
(s) => s.type == StashType.Folder && s.children && s.children.length > 0
);
if (stashTabFolder) {
console.log(
`The folder '${stashTabFolder.name}' has ${stashTabFolder.children?.length} children.`
);
const childTab = stashTabFolder.children![0];
await childTab.update();
console.log(`Childtab ${childTab.name} contains ${childTab.items?.length} items.`);
}
import { PoENinja } from "poe-api-wrappers";
const currencyOverview = await PoENinja.Currencies.getOverview("Standard", CurrencyOption.Currency);
console.log(`Fetched data for ${currencyOverview.entries.length} entries.`);
const exaltedOrb = currencyOverview.entries.find((c) => c.name == "Exalted Orb");
console.log(`One Exalted Orb is worth ${exaltedOrb?.buy?.value} Chaos orbs.`);
const divCardOverview = await PoENinja.Items.DiviniationCards.getOverview("Standard");
console.log(`Fetched data for ${divCardOverview.entries.length} entries.`);
const exaltedOrb = divCardOverview.entries.find((c) => c.name == "House of Mirrors");
console.log(`One House of Mirrors is worth ${exaltedOrb?.exaltedValue} Exalted orbs.`);
Requests to the Path of Exile API throw custom errors when something goes wrong. The thrown custom error class include the same error codes as the ones documented in the official developer API documentation. Please note that you should also check for other errors, which might occur when, for example, no internet connection is available.
try {
await PathOfExile.SessionAPI.Accounts.getProfile();
} catch (error: unknown) {
if (error instanceof PathOfExile.Errors.APIError) {
console.log(`Request failed with code ${error.code}: ${error.message}`);
}
// Handle other errors...
}