@kongyo2/nicoran-api

ニコニコ動画（nicovideo.jp）のジャンル別ランキングを取得する非公式クライアントです。

特徴

• 23ジャンル × 5期間（毎時 / 24時間 / 週間 / 月間 / 合計）に対応
• タグ絞り込み・ページネーション対応
• 4種類の抽出器を順番に試行する多段フォールバック（cheerio → node-html-parser → 正規表現2種）
• リトライ（指数バックオフ + ジッター）、タイムアウト、AbortSignal 対応
• Zod による型安全なレスポンス検証
• ランタイム依存は zod / cheerio / node-html-parser / he のみ（いずれも npm install で自動導入）
• TypeScript ファースト・ESM 専用

要件

• Node.js >= 20

インストール

npm install @kongyo2/nicoran-api

使い方

基本

import { fetchRanking } from '@kongyo2/nicoran-api';

const result = await fetchRanking({ genre: 'game', term: '24h' });

console.log(result.data.label);          // 例: 「ゲーム」
for (const item of result.data.items) {
  console.log(item.id, item.title, item.count?.view);
}

タグやページ指定

const result = await fetchRanking({
  genre: 'anime',
  term: 'week',
  tag: '今期アニメ',
  page: 2,
});

HTTP オプション（タイムアウト・リトライ・中断）

const ac = new AbortController();
setTimeout(() => ac.abort(), 5_000);

await fetchRanking({
  genre: 'vocaloid',
  http: {
    timeoutMs: 10_000,
    signal: ac.signal,
    retry: { maxRetries: 3, initialDelayMs: 500 },
    userAgent: 'my-app/1.0',
  },
});

HTML のみをパース（取得は自前で行う場合）

import { extractAndParse } from '@kongyo2/nicoran-api';

const html = await (await fetch(url)).text();
const { parsed, extractorUsed } = extractAndParse(html);

ジャンル

all, game, anime, vocaloid, voicesynth, entertainment, music, sing, dance, play, commentary, cooking, travel, nature, vehicle, technology, society, mmd, vtuber, radio, sports, animal, other

名称の代わりにジャンルキー（例: 4eet3ca4）を直接渡すことも可能です。

期間

hour | 24h（デフォルト）| week | month | total

エラー

すべての例外は NicoRankingError のサブクラスとして送出されます。

| クラス | 用途 | | --- | --- | | FetchError | HTTP エラー / ネットワーク失敗 | | TimeoutError | タイムアウト | | AbortError | ユーザー側からの中断 | | ExtractError | 全抽出器が失敗（各試行内容は attempts に格納） | | ParseError | JSON のパース失敗 | | ValidationError | Zod スキーマ検証失敗（issues を含む） |

開発

npm install
npm run typecheck
npm run lint
npm test
npm run build

ライセンス

MIT © kongyo2