l2calendar

Minimal, dependency-free JavaScript client for the public L2 Calendar API — a free, read-only JSON feed of Lineage 2 private server openings by chronicle.

• Zero dependencies, ESM, works in Node 18+ and the browser (fetch is global).
• No API key, no auth. The API sends Access-Control-Allow-Origin: *.
• Typed: ships with index.d.ts.

Install

npm install l2calendar

Quick start

import { getServers, getChronicles } from 'l2calendar';

const servers = await getServers({ chronicle: 'interlude', onlyUpcoming: true, limit: 10 });
for (const server of servers) {
  console.log(server.name, server.rate, server.opening_date, server.website_url);
}

const chronicles = await getChronicles(); // [{ id, name, slug, display_order }, ...]

API

| Function | Returns | Notes | |----------|---------|-------| | getServers(options?) | Promise<Server[]> | VIP first, then soonest opening. | | getChronicles(options?) | Promise<Chronicle[]> | The chronicle catalog (14 entries). | | getServer(name, options?) | Promise<Server \| null> | Exact name, case-insensitive. | | searchServers(query, options?) | Promise<Server[]> | Matches name, website, rate, chronicle, description, labels. | | parseRate(rate) | number \| null | "x5" → 5, "x0.5" → 0.5, "GvE" → null. | | selectServers(servers, query?) | Server[] | Apply the filters below to your own page. |

options

| Option | Type | Description | |--------|------|-------------| | chronicle | string | Chronicle slug, e.g. "interlude", "high-five", "classic", "essence". | | onlyUpcoming | boolean | Keep openings dated today or later (UTC). | | newOnly | boolean | Keep servers flagged is_new. | | minRate / maxRate | number | Rate bounds (numeric rates only). | | limit | number | 1–50, clamped. | | baseUrl | string | Override the API host (default https://l2calendar.com). |

Errors throw an L2CalendarError with an optional .status.

Server shape

{
  name: string;
  website_url: string;
  rate: string;               // "x5", "x1000", "GvE"
  opening_date: string;       // "2026-02-28"
  opening_time: string | null;
  opening_datetime_utc: string | null;
  description: string | null;
  is_vip: boolean;
  vip_level: number;
  multiproff: boolean;
  multicraft: boolean;
  is_new: boolean;
  chronicle: { name: string; slug: string } | null;
  labels: { name: string; slug: string; color: string }[];
}

Note: the public API returns a single page of up to 50 servers (VIP first, then soonest opening). The limit, rate and onlyUpcoming filters run client-side over that page — narrow with chronicle for precision.

Data source

• GET https://l2calendar.com/api/servers — optional ?chronicle=<slug>.
• GET https://l2calendar.com/api/chronicles.

About L2 Calendar

A multilingual (EN/ES/PT/RU) calendar and tracker of Lineage 2 private server openings by chronicle — l2calendar.com.

License

MIT © Dreiev