*星空文庫API

APIドキュメント

星空文庫の掲載作品と掲載者の情報を取得するためのAPIです。

  1. 概要
    1. はじめに
    2. API一覧
    3. API利用の流れ
    4. HTTPリクエスト
    5. 結果データの情報制限
    6. 構成
  2. 結果XML
    1. 書式
    2. スカラ値
    3. 配列
    4. 連想配列
  3. データ型
    1. 基本データ型
    2. 拡張データ型
      1. 拡張型work
      2. 拡張型work.link
      3. 拡張型chapter
      4. 拡張型author
      5. 拡張型author.link
    3. 列挙型
      1. 列挙型length_no
      2. 列挙型rating_no
      3. 列挙型copy_no
      4. 列挙型work_type_no
      5. 列挙型tag_no
      6. 列挙型depiction_no
      7. 列挙型author_type_no
      8. 列挙型pickup_no
  4. 各APIの引数と戻り値
    1. /api/summary
      1. 説明
      2. 引数
      3. 戻り値
    2. /api/work-list
      1. 説明
      2. 引数
      3. 戻り値
    3. /api/work
      1. 説明
      2. 引数
      3. 戻り値
    4. /api/author-list
      1. 説明
      2. 引数
      3. 戻り値
    5. /api/author
      1. 説明
      2. 引数
      3. 戻り値

概要

はじめに

本説明書では、星空文庫の作品及び作者情報を取得するためのAPIについて、その利用方法を説明します。

Your ApplicationからHTTPリクエストを受けた星空文庫APIは、XML形式の情報を返答します。
API連携イメージ

API一覧

API 説明
http://slib.net/api/summary サマリー
http://slib.net/api/work-list 作品リストの取得
http://slib.net/api/work 作品情報の取得
http://slib.net/api/author-list 作者リストの取得
http://slib.net/api/author 作者情報の取得

API利用の流れ

最初に/api/summaryを呼び出し、作品リスト及び作者リストのページ数、および最終更新時刻を得ます。

Your ApplicationからHTTPリクエスト[summary]を受けた星空文庫APIは、XML形式の[summary]情報を返答します。
サマリー

次に、/api/summaryより得た情報を元に、/api/work-list及び/api/author-listを呼び出し、アプリケーション側に最新の作品リスト及び作者リストを構築します。

Your ApplicationからHTTPリクエスト[work-list]を受けた星空文庫APIは、XML形式の[work-list]情報を返答します。
作品リスト
Your ApplicationからHTTPリクエスト[author-list]を受けた星空文庫APIは、XML形式の[author-list]情報を返答します。
作者リスト

最後に、アプリケーションユーザーの操作に応じて、必要となった個別作品の詳細情報あるいは個別作者の作品リストを、/api/workあるいは/api/authorを用いて取得します。
各々のAPIについて、詳しくは別章をご参照下さい。

HTTPリクエスト

API呼び出し時の引数は、HTTPリクエストのクエリ文字列として指定します。
たとえば、http://slib.net/api/work-list?page=2としたり、あるいはhttp://slib.net/api/work?id=100として指定します。

結果データの情報制限

API呼び出し時の引数にresponse引数を付けることで、結果データの一部を省略することが可能になります。

備考 省略表記
all 全て a
nochapter チャプター以外全て n
outline 概要 o
min 最小限の情報のみ m

以下の様に指定します。

http://slib.net/api/work?id=100&response=nochapter

各引数によって制限される項目は、各拡張型及び各API引数のresponse列を参照してください。記されている省略表記のresponse引数で呼び出された時、その項目は省略されずに結果データに含まれます。
表にresponse列が存在しない場合、response引数に関係なく、全ての情報が結果データに含まれます。

構成

本章では、API利用に関する全体の流れと、大きな章を設けなくとも説明が可能な項目について説明を行いました。
後に続く2章では結果XML の書式について、3章ではやり取りされるデータ型について、4章では各APIについて、それぞれ説明します。

結果XML

書式

結果はXMLとして返されます。
必ず以下の様な形式を取ります。

<?xml version="1.2" encoding="UTF-8"?>
<result xmlns="urn:slib:net:api:******">
<version>1.2</version>
:
:
:
</result>

最初にxmlの定義(及び文字コード指定)があり、その後にresult要素が1つだけ現れます。このresult要素の中に、全ての結果情報が含まれます。resultの属性であるxmlnsは必ず「urn:slib:net:api:******」の形式になっており、「******」の部分はAPIごとに固定です。
なお、結果XMLを構成する各要素は、スカラ値/配列/連想配列の3種類のデータ表現から構成されます。そしてそれらは、一定ルールに基づくことで、パースすることが可能です。一番外側のresult要素は、必ず、連想配列データの扱いとなります。result要素は必ずversionという子要素を持っています。

versionはスカラ値データであり、その値は現時点では常に1.2となります。ここに1.2以外の値が来た場合、本説明書に記されていない未知の規則が適用されている可能性があります。
なお、各APIの説明の項において、versionについて省略しておりますが、実際に得られるデータ中にはversion子要素が存在することに注意して下さい。

スカラ値

スカラ値は、文字列や数値といった単体で存在するデータです。
XML内では、以下の様な形式で表されます。

<scala>hoge</scala>

scalaの部分は例であり、ここにはデータ名が来ます。
hogeの部分が、スカラ値データにあたります。
なお、XML内においてスカラ値データは、特殊文字が以下の様にエンコードされています。

エンコード前 エンコード後
& &amp;
< &lt;
> &gt;
改行コード &#xA;

配列

配列は、データの羅列からなるデータです。
XML内では、以下の様な形式で表されるデータです。

<data-list type=”array”>
<data> ... </data>
<data> ... </data>
:
:
<data> ... </data>
</data-list>

dataの部分は例であり、ここにはデータ名が来ます。
各「...」の部分には、配列要素のデータが来ます。
外側の開始タグにはtype="array"が付き、要素名はデータ名に「-list」の接尾辞が付いたものとなります。

並べられたデータには順序がありますが、名前はついておりません。内側の要素名は全てデータ名と一致します。

配列内の要素のデータ型は、スカラ値または連想配列となります。また、同一配列内の各要素のデータ型は必ず一致します。

連想配列

連想配列は、名前のついたデータの羅列からなるデータです。
XML内では、以下の様な形式で表されるデータです。

<obj>
<hoge> ... </hoge>
<fuga> ... </fuga>
<foo> ... </foo>
<bar> ... </bar>
</obj>

objの部分は例であり、ここには連想配列データのデータ名が来ます。
また、hoge, fuga, foo, barの部分も例であり、各々の子要素のデータ名が来ます。

連想配列内の各要素のデータ型には、制限がありません。
また、各要素ごとのデータ型は個別に定まり、同一とは限りません。
詳細については、拡張データ型の定義に従って下さい。

データ型

基本データ型

基本的なデータ型については、以下の様に定めます。

型名 XML表現 備考
uint スカラ値 符号なし整数値 15
string スカラ値 改行を含まない文字列 こんにちは
text スカラ値 改行を含む文字列 あいうえお
かきくけこ
enum-uint スカラ値 符号なし整数値で表される列挙型データ。値の示す意味については、列挙型の項を参照。 3
date スカラ値 日時タイムスタンプ 2011-01-01T12:23:34+09:00
url スカラ値 URL http://slib.net/
image-url スカラ値 画像のURL http://slib.net/data/***.jpg
***[] 配列 ***の配列型 [***, ***, ***]
object 連想配 列連想配列型

拡張データ型

連想配列であるobjectは、状況に合わせ様々な子要素を持ちます。
以下に、各拡張データ型について定義します。
ただし、同じ拡張データ型であっても、呼び出すAPIによっては、子要素の一部が存在しない場合があります。

拡張型work

データ名 データ型 データ値の例 response 備考
id uint 100 anom 作品のID
lang string ja anom 使用言語
title string 走れメロス anom 作品の題名
letter_count uint 10397 ano 作品の文字数
length_no enum-uint 2(列挙型length_noを参照) ano 作品の文章量区分
rating_no enum-uint 1(列挙型rating_noを参照) ano 作品の対象年齢区分
copy_no enum-uint 99(列挙型copy_noを参照) ano 作品の権利区分
work_type_no enum-uint 1(列挙型work_type_noを参照) ano 作品の形式区分
tag_no enum-uint[] [2, 8] ano 作品の要素区分の配列
depiction_no enum-uint[] [21, 31] ano 作品の表現区分の配列
author_type_no enum-uint 1(列挙型author_type_noを参照) ano 作品の作者区分
pickup_no enum-uint 1 ano 選者による選定作品
icon_url image-url http://slib.net/data/***.jpg ano 作品画像
description text 素朴な牧人の青年~ ano 作品の概要
foreword text おそらく私達の~ an 作品のまえがき
afterword text 古伝説とシルレルの詩から。 an 作品のあとがき
chapter object (拡張型chapterを参照) a 作品の本文
※/api/workの呼び出し時にのみ存在します。
link object (拡張型work.linkを参照) anom 作品データを得るための各URL
※/api/work-list及び/api/authorの呼び出し時にのみ存在します。
author_id uint 100 om 作者ID
※結果データ中に作者情報が含まれない場合に付与されます。
author object (拡張型authorを参照) an 作者情報
※/api/work-listの呼び出し時にのみ存在します。
author_name text 太宰治 ano 作品の原作者名
reg_date date 2011-01-01T12:23:34+09:00 anom 作品の作成日時
mod_date date 2011-01-01T12:23:34+09:00 anom 作品の最終更新日時

拡張型work.link

データ名 データ型 データ値の例 備考
html url http://slib.net/100 html形式の作品データURL
epub url http://slib.net/100.epub epub形式の作品データURL
pdf url http://slib.net/100.pdf PDF形式の作品データURL
pdf_vertical url http://slib.net/100.v.pdf PDF形式(縦書き)の作品データURL
text url http://slib.net/100.txt テキスト形式の作品データURL
text_aozora url http://slib.net/100.aozora.txt 青空文庫準拠テキスト形式の作品データURL
api_xml url http://slib.net/api/work?id=100 XML形式の作品データURL

拡張型chapter

データ名 データ型 データ値の例 備考
title string 第一章 チャプターのタイトル
icon_url image-url http://slib.net/data/***.jpg チャプター画像
body text メロスは激怒した。必ず、かの邪智暴虐~ チャプター本文

拡張型author

データ名 データ型 データ値の例 response 備考
id uint 100 anom 作者のID
name string 太宰治 anom 作者名
country string JP ano 著作権所轄地
lang string[] ["ja"] anom 使用言語
description string 昭和を代表する日本の小説家~ ano 一行紹介
detail text 1933年(昭和8年)より~ an 自己紹介
icon_url image-url http://slib.net/data/***.jpg ano プロフィール画像
work_count uint 1 anom 作品数
link object[] (拡張型author.linkを参照) ano 作者に関するリンク
reg_date date 2011-01-01T12:23:34+09:00 anom 作者情報の作成日時
mod_date date 2011-01-01T12:23:34+09:00 anom 作者情報の最終更新日時

拡張型author.link

データ名 データ型 データ値の例 備考
label string ほげほげ リンク名
url url http://example.com/ リンク先URL

列挙型

enum-uint型データの各整数値が示す値の意味を、以下に示します。

列挙型length_no

整数値 意味
1 掌編
2 短編
3 中編
4 長編

列挙型rating_no

整数値 意味
1 全年齢対象
11 幼児向け
12 児童向け
13 青年向け
21 成人向け

列挙型copy_no

整数値 意味 ライセンス表示
1 Copyrighted 著作権法内での利用のみを許可します。
11 CC BY-NC-ND 原著作者の表示・非営利・改変禁止の条件で、作品の利用を許可します。
12 CC BY-NC-SA 原著作者の表示・非営利・CCライセンス継承の条件で、作品の利用を許可します。
13 CC BY-NC 原著作者の表示・非営利の条件で、作品の利用を許可します。
14 CC BY-ND 原著作者の表示・改変禁止の条件で、作品の利用を許可します。
15 CC BY-SA 原著作者の表示・CCライセンス継承の条件で、作品の利用を許可します。
16 CC BY 原著作者の表示の条件で、作品の改変や二次創作などの自由な利用を許可します。
21 Derivative work 二次創作物であり、原作に関わる一切の権利は原作権利者が所有します。
99 Public Domain 著作権を主張しない、または消滅しました。

列挙型work_type_no

整数値 意味
1 小説
11 随筆・エッセイ
21 韻文詩
31 散文詩

列挙型tag_no

整数値 意味
1 ファンタジー
2 青春
3 恋愛
4 冒険
5 アクション
6 サスペンス
7 ミステリー
8 時代・歴史
9 ホラー
10 SF
11 コメディ

列挙型depiction_no

整数値 意味
1 強い暴力的表現
11 強い性的表現
21 強い反社会的表現
31 強い言語・思想的表現

列挙型author_type_no

整数値 意味
1 作者
2 編集者
3 翻訳者

列挙型pickup_no

整数値 意味
0 ピックアップ作品でない
1 ピックアップ作品である

各APIの引数と戻り値

/api/summary

説明

作品リスト及び作者リストの各ページ数及び更新日時を取得します。
こうして得られた情報を用いて、/api/work-list/api/author-listの呼び出し回数や再取得の有無を判断することになります。

引数

ありません。

戻り値

データ名 データ型 データ値の例 説明
work_count uint 230 作品数
work_page_count uint 3 作品リストのページ数
work_mod_date date 2011-01-01T12:23:34+09:00 作品の最終更新日時
author_count uint 190 作者数
author_page_count uint 2 作者リストのページ数
author_mod_date date 2011-01-01T12:23:34+09:00 作者の最終更新日時

/api/work-list

説明

ページごと(1ページあたり約100件を設定)の作品概要情報を取得します。概要には本文などの一部の情報が含まれません。
アプリケーション利用者に、閲覧可能な作品の一覧を提供することが、このAPIの目的です。こうして得られた作品リストデータを元に、必要に応じて/api/workを用いることで、個別の作品の詳細データを取得して下さい。

引数

引数名 データ型 引数の例 説明
page uint page=2 取得したいページ番号を指定します。最初のページは0ではなく1です。
省略した場合は1とみなされます。

戻り値

データ名 データ型 データ値の例 説明
work object[] (拡張型workを参照) 指定したページ内の各作品概要の配列

/api/work

説明

個別作品の詳細データを取得します。

引数

引数名 データ型 引数の例 説明
id uint id=100 取得したい作品のIDを指定します。
省略できません。

戻り値

データ名 データ型 response データ値の例 説明
work object (拡張型workを参照) anom 指定した作品の内容を含む詳細データ
author object (拡張型authorを参照) an 指定した作品の作者情報

/api/author-list

説明

ページごと(1ページあたり約100件を設定)の作者情報を取得します。
アプリケーション利用者に、作者の一覧を提供することが、このAPIの目的です。こうして得られた作者リストデータを元に、必要に応じて/api/authorを用いることで、個別の作者の作品概要リストを取得することができます。

引数

引数名 データ型 引数の例 説明
page uint page=2 取得したいページ番号を指定します。最初のページは0ではなく1です。
省略した場合は1とみなされます。

戻り値

データ名 データ型 データ値の例 説明
author object[] (拡張型authorを参照) 指定したページ内の各作者情報の配列

/api/author

説明

個別作者情報及び、その作者の作品概要リストを取得します。

引数

引数名 データ型 引数の例 説明
id uint id=100 取得したい作者のIDを指定します。
省略できません。

戻り値

データ名 データ型 データ値の例 response 説明
author object (拡張型authorを参照) anom 指定した作者の情報
work object[] (拡張型workを参照) an 指定した作者の各作品概要の配列

以上。

ガイドライン

星空文庫APIは、利用規約に同意の上、ガイドラインに従ってご利用ください

星空文庫API仕様書
日付 更新
2012-06-12 ver 1.2 項目追加: データ型-拡張データ型-拡張型work(author_name, pickup), 拡張型work.link(aozora.text)
2011-09-15 ver 1.0 新規作成

APIについてご不明な点などございましたら、お問い合わせください。