なろうデベロッパー

小説家になろう

なろう殿堂入りAPI

なろう殿堂入りAPIは作品が過去にどのランキングに載ったか（殿堂入りしたか）を調査できるAPIです。
対象となるランキングは「小説を読もう！で公開しているランキング」で2013年5月1日以降の日間、週間、月間、四半期ランキングの一部です。
現在、R18ランキングを取得するAPIは提供しておりません。

なろう殿堂入りAPIはHTTPでのリクエストに対してJSON形式、JSONP形式又はYAML形式で応答します。
すべての殿堂入りを調査できるわけではありません。

APIを使うためにはJavaScriptあるいはPerl/PHP/Ruby/Java/C言語などでプログラミングが必要です。

出力形式

JSON形式、JSONP形式またはYAML形式となっています。
標準はYAML形式となっていますが、outパラメータで変更できます。
文字コードはUTF-8です。

APIのURL

https://api.syosetu.com/rank/rankin/

GETで送信。POSTでは受信できません。
ncodeは必須です。指定しない場合、Error: Novel not found.が出力されます。

GETパラメータ

パラメータ 値 説明
gzip int(1～5)

gzip圧縮してgzipファイルとして返します。
gzip圧縮レベルを1～5で指定できます。
転送量上限を減らすためにも推奨
out string

出力形式をyamlまたはjsonまたはphpを指定。
未指定時はYAMLになる。outパラメータの詳細
ncode string

Nコードです。
N0001AのようにNコードを指定してください。

https://api.syosetu.com/rank/rankin/?ncode=N0001A

N0001Aが過去にどのランキングに掲載されたかを調べるURLです。

outパラメータの詳細

出力形式を指定できます。
jsonまたはyamlまたはphpで指定してください。

  • yaml
    YAML形式(デフォルト)
  • json
    JSON形式
  • php
    PHPのserialize()
  • jsonp
    JSONP形式

JSONPの使い方

JSONPを利用することでJavaScriptから直接、APIを利用できるようになります。

  • callback
    コールバック関数名。コールバック関数名には半角英数字など/^$?[a-zA-Z0-9\[\]\.\_]+$/ (perl) の正規表現に一致する関数名を指定してください。

https://api.syosetu.com/rank/rankin/?out=jsonp&callback=call&ncode=N0001A

JSONP形式でコールバック関数名をcallにしたい場合のURLです。

YAML形式の出力に関する動作について

出力形式にYAMLを指定した場合、パラメータを指定する事で利用するライブラリを変更できます。

パラメータ 値 説明
libtype int

利用するライブラリを指定できます。
未指定もしくは1以下の値を指定した場合、従来通りのライブラリを利用します。
2以上の値を指定すると、新ライブラリを利用します。
新ライブラリでは以下の点が従来のライブラリと異なります。

  • 文字列と数値の型指定が厳格化します。
  • マルチバイト文字や一部の制御文字がエスケープ処理されます。

https://api.syosetu.com/rank/rankin/?ncode=N0001A&libtype=1

従来通りのライブラリで出力を行ないます。
文字列が格納される部分が数値で構成されている場合でも、数値はダブルクォートで囲まれません。

https://api.syosetu.com/rank/rankin/?ncode=N0001A&libtype=2

新ライブラリで出力を行ないます。
文字列が格納される部分が数値で構成されている場合、数値がダブルクォートで囲まれます。

出力

APIサーバが出力する文字コードはUTF-8です。デフォルトはYAML形式です。
outパラメータでJSON形式などにも変更できます。

要素 説明
rtype

ランキングタイプです。日付-種別の形式です。種別は日間の場合はd、週間の場合はw、月間の場合はm、四半期の場合はqとなります。
pt

ポイント
rank

順位1～300

制約について

殿堂入りの対象となるランキングのデータは2013年5月1日以降の「小説を読もう！で公開しているランキング」を蓄積(バックアップ)したものです。

しかしながら、すべてのランキングの蓄積はサーバリソースの制約上、不可能であり、週間は毎週火曜日のみ、月間と四半期は毎月1日のランキングを蓄積し、これらの蓄積されたランキングに掲載された場合のみ、殿堂入りとして結果を出力します。
そのため、たとえば、月曜日に週間ランキングに掲載された場合でも、次の火曜日に週間ランキングに掲載されていない場合は、殿堂入りとして扱われません。

また、「小説を読もう！で公開しているランキング」の日間ランキングは1日3回更新されていますが、このAPIでは午前4時～午前7時に作成した日間ランキングのみを蓄積しAPIで提供しています。
午後の日間ランキングに掲載され、翌朝の日間ランキングに掲載されなかった場合は殿堂入りと認定されません。
予めご了承願います。

利用制限

利用制限は現在、休止しています。
負荷状況により今後、導入されることがあるためキャッシュの導入など、利用制限を想定したシステム設計をお願いします。ただし、古い情報を誤って掲載しないよう一定期間(長くても２週間)でキャッシュの更新・削除をお願いします。

IPアドレスごとに利用制限を行います。
1日の利用上限は80,000または転送量上限400MByteです。
利用制限は初回アクセスから24時間が適用範囲です。
初回のアクセスから24時間後に回数と転送量を記録していたカウンタと初回アクセス時刻をリセットします。
なお、1日の利用上限を超えた場合、エラーの発生確率が増します。
混雑状況にもよりますが、リクエスト回数または転送量が利用上限の120%を超えるとほとんど接続できなくなります。

備考：利用制限カウンタは厳密ではなく多少のマージンを設けてあります。
転送量は圧縮することで減らせます。

転送量制限の回避方法
  • gzip=5を指定し、gzipファイルで受信する。
    デメリットとして受け取り側で解凍する手間は発生するが、かなりの転送量を削減できる。
  • YAML形式を使う。一番容量が小さいため。

遅延について

データベースサーバは日本国内の複数拠点に分散されていることがあります。
APIから小説データベースに接続した場合、原則としてスレーブサーバにつながります。
マスタサーバとスレーブサーバ間は10秒以内にデータを同期しています。

しかし、何らかのネットワーク障害が発生した場合、遅延が発生し、サーバによってデータにばらつきが生じることがあります。
また、実際にランキングのデータが修正されてからAPIに反映されるまで遅れがあります。