openalbion

TypeScript wrapper for the OpenAlbion API — Albion Online game data.

API Home & Documentation | GitHub

Installation

npm install openalbion

Note: This library uses the native fetch API (Node 18+). For older Node versions, install node-fetch and polyfill globally.

Quick Start

import OpenAlbion from "openalbion";

const api = new OpenAlbion();

// Get all weapons
const weapons = await api.weapons.getAll();

// Get T4 weapons
const t4Weapons = await api.weapons.getByTier(4);

// Get weapon stats – you can use the numeric ID or the unique item name
const stats = await api.weaponStats.getByWeapon(2);
const statsByName = await api.weaponStats.getByWeapon(
  "T8_ARMOR_PLATE_VANITY_PERFTEST_PARTICLEONLY@3"
);

// Get spells for a weapon
const spells = await api.spells.getByWeapon(1);

Item Identifiers

The OpenAlbion API uses numeric IDs for items. This library automatically bundles a generated mapping from item names (e.g. "T8_ARMOR_PLATE_VANITY_PERFTEST_PARTICLEONLY@3") to their numeric IDs.

You can use either the numeric ID or the unique name string anywhere an item ID is required (e.g. getByWeapon, getByArmor, getSpells, etc.).

Two constants are exported for convenience:

• ItemId: an object mapping item names to their IDs.
• ItemName: an object mapping IDs back to names.

import { ItemId, ItemName } from "openalbion";

console.log(ItemId["T8_ARMOR_PLATE_VANITY_PERFTEST_PARTICLEONLY@3"]); // 7492
console.log(ItemName[7492]); // "T8_ARMOR_PLATE_VANITY_PERFTEST_PARTICLEONLY@3"

If you need an up‑to‑date list (for newly added items), you can fetch the latest mapping directly from the source:

const latestMap = await api.fetchLatestItemIds();
// Use it as a custom map in any method
const stats = await api.weaponStats.getByWeapon("NEW_ITEM_NAME", {
  customIdMap: latestMap,
});

API Reference

new OpenAlbion(baseUrl?)

Creates a new client. Optionally override the base URL (defaults to https://api.openalbion.com/api/v3).

api.categories

| Method | Description | | --- | --- | | getByType(type) | Get categories by type ("weapon", "armor", "accessory", "consumable") | | getWeaponCategories() | Shorthand for getByType("weapon") | | getArmorCategories() | Shorthand for getByType("armor") | | getAccessoryCategories() | Shorthand for getByType("accessory") | | getConsumableCategories() | Shorthand for getByType("consumable") |

api.weapons

| Method | Description | | --- | --- | | getAll() | All weapons | | getByCategory(categoryId) | Filter by category ID | | getBySubcategory(subcategoryId) | Filter by subcategory ID | | getByTier(tier) | Filter by tier number (e.g. 4 for T4) | | getBy(filters) | Filter by any combination of category_id, subcategory_id, tier |

api.weaponStats

| Method | Description | | --- | --- | | getByWeapon(weaponId, options?) | Stats grouped by enchantment level, then by quality. weaponId can be a numeric ID or an item name string. Optionally pass { customIdMap } to override the built‑in mapping. |

api.armors

| Method | Description | | --- | --- | | getAll() | All armors | | getByCategory(categoryId) | Filter by category ID | | getBySubcategory(subcategoryId) | Filter by subcategory ID | | getByTier(tier) | Filter by tier | | getBy(filters) | Combined filters |

api.armorStats

| Method | Description | | --- | --- | | getByArmor(armorId, options?) | Stats grouped by enchantment level, then by quality. Accepts a numeric ID or an item name. |

api.accessories

| Method | Description | | --- | --- | | getAll() | All accessories (capes, bags, mounts) | | getByCategory(categoryId) | Filter by category ID | | getBySubcategory(subcategoryId) | Filter by subcategory ID | | getByTier(tier) | Filter by tier | | getBy(filters) | Combined filters |

api.accessoryStats

| Method | Description | | --- | --- | | getByAccessory(accessoryId, options?) | Stats grouped by enchantment level, then by quality. Accepts a numeric ID or an item name. |

api.consumables

| Method | Description | | --- | --- | | getAll() | All consumables (food & potions) | | getByCategory(categoryId) | Filter by category ID | | getBySubcategory(subcategoryId) | Filter by subcategory ID | | getByTier(tier) | Filter by tier | | getBy(filters) | Combined filters |

api.consumableStats

| Method | Description | | --- | --- | | getByConsumable(consumableId, options?) | Stats grouped by enchantment level, then by quality. Accepts a numeric ID or an item name. |

api.consumableCraftings

| Method | Description | | --- | --- | | getByConsumable(consumableId, options?) | Crafting recipes grouped by enchantment level. Accepts a numeric ID or an item name. |

api.spells

| Method | Description | | --- | --- | | getByWeapon(weaponId, options?) | Spells grouped by slot (First, Second, Third, Passive). Accepts a numeric ID or an item name. | | getByArmor(armorId, options?) | Spells grouped by slot (Fifth Slot, Passive). Accepts a numeric ID or an item name. | | getByAccessory(accessoryId, options?) | Passive spells for an accessory. Accepts a numeric ID or an item name. |

fetchLatestItemIds()

Fetches the most recent item ID mapping from the official source. Returns a Record<string, number>.

const latestMap = await api.fetchLatestItemIds();

You can pass this map as customIdMap to any method that accepts an item identifier, ensuring that newly added items are recognised.

Constants

import { CATEGORY_TYPES, ENCHANTMENT_LABELS, QUALITY_LEVELS } from "openalbion";

CATEGORY_TYPES;       // ["weapon", "armor", "accessory", "consumable"]
ENCHANTMENT_LABELS;   // { 0: "Common", 1: "Uncommon", 2: "Rare", 3: "Epic", 4: "Legendary" }
QUALITY_LEVELS;       // ["Normal", "Good", "Outstanding", "Excellent", "Masterpiece"]

Error Handling

import OpenAlbion, { OpenAlbionError } from "openalbion";

const api = new OpenAlbion();

try {
  const weapons = await api.weapons.getAll();
} catch (err) {
  if (err instanceof OpenAlbionError) {
    console.error(`API error ${err.statusCode} at ${err.url}: ${err.message}`);
  }
}

Types

All TypeScript interfaces are exported:

import type {
  Category, Subcategory, CategoryType,
  Weapon, WeaponStatGroup, WeaponStatRecord,
  Armor, ArmorStatGroup, ArmorStatRecord,
  Accessory, AccessoryStatGroup, AccessoryStatRecord,
  Consumable, ConsumableStatGroup, ConsumableStatRecord,
  ConsumableCraftingGroup, ConsumableCrafting, CraftingRequirement,
  Spell, SpellSlotGroup, SpellAttribute,
  StatEntry, Quality, EnchantmentLevel,
  WeaponFilters, ArmorFilters, AccessoryFilters, ConsumableFilters,
} from "openalbion";

License

MIT