NDL Face の全エンドポイントの仕様と使用例
Base URL: https://face.ldas.jp
/api/expressionsキーワード・感情カテゴリ・身体部位等で絞り込み検索。ページネーション、ソート、ファセット集計に対応。
| 名前 | 型 | 説明 |
|---|---|---|
keyword | string | 全文検索キーワード（surface, context対象） |
emotion | string | 感情カテゴリ（カンマ区切りで複数指定可）例: 喜び・笑い,悲しみ・哀れ |
body_part | string | 身体部位（カンマ区切りで複数指定可）例: 目,口 |
valence | string | 感情極性（カンマ区切りで複数指定可）例: positive,negative |
gender | string | 性別（カンマ区切りで複数指定可）例: male,female,unknown,mixed |
pid | string | 作品のPID（NDLデジコレ識別子）で絞り込み |
limit | number | 取得件数（デフォルト: 20）例: 20 |
offset | number | オフセット（デフォルト: 0）例: 0 |
sort | string | ソートフィールド（デフォルト: _score）例: _score | emotion | body_part | intensity |
order | string | ソート順（デフォルト: desc）例: desc | asc |
curl "https://face.ldas.jp/api/expressions?emotion=喜び・笑い&limit=10"{
"hits": [
{
"id": "abc123",
"pid": "1882646",
"surface": "涙にくれる",
"context": "別れの場にて涙にくれる女の…",
"emotion": "悲しみ・哀れ",
"body_part": "目",
"valence": "negative",
"intensity": "high",
"character": "世之介",
"pages": [131],
"title": "好色一代男 研究会講録"
}
],
"total": 591,
"facets": {
"emotions": [{ "key": "悲しみ・哀れ", "count": 137 }],
"body_parts": [{ "key": "顔", "count": 120 }],
"valences": [{ "key": "negative", "count": 200 }],
"intensities": [{ "key": "medium", "count": 300 }],
"genders": [{ "key": "male", "count": 250 }]
}
}/api/expressions/{id}Elasticsearch ドキュメントIDを指定して1件取得。
| 名前 | 型 | 説明 |
|---|---|---|
id必須 | string | ドキュメントID（パスパラメータ） |
curl "https://face.ldas.jp/api/expressions/abc123"{
"id": "abc123",
"pid": "1882646",
"surface": "涙にくれる",
"context": "別れの場にて涙にくれる女の…",
"emotion": "悲しみ・哀れ",
"body_part": "目",
"valence": "negative",
"intensity": "high",
"character": "世之介",
"pages": [131],
"title": "好色一代男 研究会講録"
}/api/expressions/by-bookPIDを指定して、その作品に含まれる表現をページ順で取得。
| 名前 | 型 | 説明 |
|---|---|---|
pid必須 | string | 作品のPID（必須）例: 1882646 |
limit | number | 取得件数（デフォルト: 10） |
offset | number | オフセット（デフォルト: 0） |
curl "https://face.ldas.jp/api/expressions/by-book?pid=1882646&limit=10"{
"hits": [ ... ],
"total": 591
}/api/books登録済みの全作品を、表現件数・著者・年代・ジャンル・感情カテゴリ別分布と共に返す。
curl "https://face.ldas.jp/api/books"[
{
"pid": "1882646",
"title": "好色一代男 研究会講録",
"author": "井原西鶴",
"year": 1682,
"genre": "好色物",
"ndc": null,
"expression_count": 591,
"emotions": {
"悲しみ・哀れ": 137,
"色気・艶": 96,
"喜び・笑い": 82
}
}
]/api/stats感情カテゴリ・身体部位・感情極性の集計値と、総件数を返す。
curl "https://face.ldas.jp/api/stats"{
"emotions": { "悲しみ・哀れ": 137, "色気・艶": 96 },
"bodyParts": { "顔": 120, "目": 98 },
"valences": { "negative": 200, "positive": 150 },
"total": { "value": 591 }
}/api/analytics作品別感情分布、感情×身体部位クロス集計、感情極性分布など、可視化用の集計データを返す。
curl "https://face.ldas.jp/api/analytics"{
"booksEmotions": [
{
"pid": "1882646",
"title": "好色一代男 研究会講録",
"total": 591,
"emotions": { "悲しみ・哀れ": 137, ... }
}
],
"emotionBodypartMatrix": [
{
"emotion": "悲しみ・哀れ",
"bodyParts": { "目": 45, "顔": 30 },
"total": 137
}
],
"valenceDistribution": { "negative": 200, "positive": 150 },
"emotionDistribution": { "悲しみ・哀れ": 137, ... },
"bodyPartDistribution": { "顔": 120, ... }
}Expression（表情表現）オブジェクトのフィールド定義
| フィールド | 型 | 説明 |
|---|---|---|
id | string | ElasticsearchドキュメントID |
pid | string | NDLデジタルコレクション永続的識別子 |
title | string | 作品名 |
surface | string | 抽出された表現（表層形） |
context | string | 表現の前後の文脈テキスト |
emotion | string | 感情カテゴリ（喜び・笑い、悲しみ・哀れ等） |
body_part | string | 身体部位（顔、目、口、頬等） |
valence | string | 感情極性（positive / negative / neutral / ambiguous） |
intensity | string | 強度（low / medium / high） |
character | string | 表現の主体となる人物名 |
pages | number[] | 原典でのコマ番号 |
author | string? | 著者名（作品メタデータ） |
year | number? | 成立年（西暦） |
genre | string? | ジャンル |
%E5%96%9C%E3%81%B3）