RandNext API

48種類のRandNextツールに対応する無料の読み取り専用JSONエンドポイントです。APIキーなしで、数字、色、日付、サイコロ、厳選項目などを生成できます。バージョン1のベースパスは /api/v1 です。

クイックスタート

curl https://randnext.com/api/v1/jokes/random

curl "https://randnext.com/api/v1/tools/random-number?min=1&max=100&count=5&unique=true"

const res = await fetch("https://randnext.com/api/v1/quotes/random?category=wisdom");
const quote = await res.json();
console.log(`“${quote.text}” — ${quote.author}`);

エンドポイント

厳選コンテンツには一覧、ランダム、ID指定の各エンドポイントがあります。生成ツールはツールのslugに基づく統一エンドポイントを使用します。

リクエスト	戻り値
`GET /api/v1/{type}/random`	ランダムな項目を1件
`GET /api/v1/{type}?limit=1..20`	`{ data: Item[], count }` — 重複しないランダム項目（既定10件）
`GET /api/v1/{type}/{id}`	IDで指定した項目を1件（キャッシュ可能）
`GET /api/v1/tools/{slug}`	対応する44種類のユーティリティツールから結果を生成
`GET /api/v1/draws/{id}`	抽選ピッカーの抽選記録。コミットメント、応募者リストのハッシュ、抽選時刻後に公開されるシードと当選者を含みます。期限を迎えた抽選を読み取ると結果が公開されます。
`GET /api/v1/draws/{id}/entries`	ロック済みの応募者リストを text/plain でバイト単位までそのまま返します。SHA-256は entries_hash です。非公開リストには主催者の管理トークンが必要です。
`POST /api/v1/draws/{id}/cancel`	主催者のみ：抽選時刻前に抽選をキャンセルします。記録はキャンセル済みとして公開されたままです。
`PATCH /api/v1/draws/{id}`	主催者のみ：listed を true または false に設定するか、purge_entries を true にして抽選後に保存済みリストを削除します。
`GET /api/v1/health`	サービス状態
`GET /api/v1/openapi.json`	OpenAPI 3.1記述

抽選主催者の操作では Authorization: Bearer <管理トークン> を送信します。randnext.comまたはサーバー側コードからのみ受け付け、他のウェブサイトからは利用できません。抽選の再計算にはrandnext-draw-v1仕様を使用してください。

クエリパラメータ

category — ジョーク：general, programming, dad, pun, animal、引用：inspirational, life, work, humor, wisdom、質問：icebreaker, classroom, friends, deep, would-you-rather、単語：noun, verb, adjective, adverb。
safety — family（ファミリー向けのみ）または general（既定：ファミリー向けと一般向け）。成人向けコンテンツは返されません。
単語のみ： min_length, max_length （1～30）、starts_with（1文字）。
生成パラメータはツールごとに異なります。一般的なオプションは count, min, max, group, unique, sort. 各ツールページに実行可能なリクエスト例があります。
不明なパラメータや許容範囲外の値には 400 INVALID_PARAMETER が返されます。

対応ツール

現在48種類のツールに公開エンドポイントがあります。ツールページでパラメータを確認し、そのまま実行できるcurlリクエストをコピーできます。

ランダムジョークランダム名言ランダム質問ランダム英単語ランダム国ランダム都市ランダム米国州ランダム大陸ランダム旅行先ランダム言語ランダム動物ランダム元素ランダム惑星ランダム天体ランダム天気ランダム星座チェスマスランダム季節ランダム月ランダム曜日ランダム方角何食べるランダムドリンクランダムコーヒーランダムデザートランダムアクティビティランダム趣味ランダム職業ランダムな物ランダム年ランダム年齢ランダム誕生日ランダム時刻ランダム角度ランダムパーセントランダム小数偶数・奇数ランダム素数ランダム座標ランダム2進数乱数ランダムカラーランダム日付ランダム文字サイコロコイントスイエス・ノーじゃんけん

レスポンス

ユーティリティ生成ツールは統一された形式で返します：

{
  "tool": "random-number",
  "data": [
    { "value": "18" },
    { "value": "72" }
  ],
  "count": 2,
  "permalink": "https://randnext.com/random-number"
}

厳選コンテンツのエンドポイントでは、より詳しい出典とライセンス情報も返します：

{
  "id": "qt_000001",
  "type": "quote",
  "text": "Well done is better than well said.",
  "author": "Benjamin Franklin",
  "category": "wisdom",
  "tags": [],
  "language": "en",
  "safety_level": "family",
  "source_url": null,
  "license": "public-domain",
  "attribution": "Poor Richard’s Almanack (1737)",
  "permalink": "https://randnext.com/random-quote?id=qt_000001"
}

attribution が null でない場合は、コンテンツの横に必ず表示してください。

エラー

{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Please try again later." } }

400	INVALID_PARAMETER	パラメータが無効です。例：不明なカテゴリ、範囲外のlimit。
401	UNAUTHORIZED	抽選主催者の操作のみ：管理トークンがないか、正しくありません。
404	NOT_FOUND	種類またはIDが不明、項目が削除済み、または条件に一致する項目がありません。
409	CONFLICT	抽選主催者の操作のみ：現在の抽選状態では操作できません。
429	RATE_LIMITED	リクエストが多すぎます。Retry-Afterに示された秒数だけ待ってください。
500	INTERNAL_ERROR	サーバー側で問題が発生しました。
503	SERVICE_UNAVAILABLE	一時的に利用できないか、メンテナンス中です。

制限とキャッシュ

IPアドレスごとに1分あたり60件、1日あたり1,000件です。すべてのレスポンスに X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset が含まれます。
ランダムエンドポイントはキャッシュされません。ID指定のレスポンスと確定済み抽選記録は最大1時間キャッシュされる場合があります。
任意のオリジンからのGETリクエストでCORSを利用できます。

利用条件

無料利用には、randnext.comへの「Powered by RandNext」リンクを見える場所に表示する必要があります。
attribution フィールドがある場合は必ず表示してください。
コンテンツライブラリ全体をダウンロードして再公開または再販売しないでください。
SLAはありません。制限の変更や、不正利用トラフィックの遮断を行う場合があります。

サポート

公開APIは現在48種類のツールに対応しています。パスワード、PIN、秘密トークンなどセキュリティ上重要な生成ツールはブラウザ内のみで動作し、生成された秘密情報がサーバーに届くことはありません。APIに関する質問や問題の報告は、support@randnext.comまでエンドポイントとレスポンス状態を添えてメールしてください。