| name | ndl_opensearch |
| description | NDL OpenSearch API scraper for Taiwan-related books (Publication Intel v3.1) |
ndl_opensearch Scraper
機能説明
- 来源名:
ndl_opensearch
- URL:
https://ndlsearch.ndl.go.jp/api/opensearch
- 資料類型: 国立国会図書館（NDL）蔵書データベースの台湾関連書籍（mediatype=1）
NDL OpenSearch API に q=台湾, mediatype=1, cnt=100 でクエリし、書籍書誌情報を取得する。
技術規格
| 項目 | 詳細 |
|---|
| プロトコル | HTTP GET / RSS 2.0 with Dublin Core namespaces |
| Namespace | dc: http://purl.org/dc/elements/1.1/ / dcterms: http://purl.org/dc/terms/ |
| Pagination | &idx= (1-based offset), 100件/ページ, 最大 500 件 |
source_id 形式 | ndl_{dc:identifier の末尾数字} または ndl_{md5(link)[:12]} |
| 発売日フィールド | dcterms:issued → dc:date → pubDate（優先度順） |
| 発売日形式 | YYYY, YYYY-MM, YYYY-MM-DD いずれも対応 |
来源分流説明
⚠️ NDL は発売日降順ソートではない
NDL OpenSearch のデフォルトソートは相関度 / 書誌 ID であり、発売日降順ではない。
このため、古い書籍が先頭ページに登場することがある。
対策: 180 日 client-side フィルタを必ず実施（cutoff = date.today() - timedelta(days=180)）。
Server-side の日付フィルタは NDL API が提供していないため省略できない。
Active ビュー表示について
start_date が 30 日以上前の書籍 → is_active=true のまま DB に残るが、ウェブサイトの「開催中」フィルタからは外れる（仕様どおり）- 書籍は単日時間点であるため
end_date = start_date（単日イベント扱い）
ZERO_EVENT_OK 理由
180 日ウィンドウ内に台湾関連書籍が 0 件の日は正常（出版サイクルに依存）。
health_check.py の ZERO_EVENT_OK_SOURCES に登録済み。
特殊規則
- 純出版 invariant（exact-only）: pure 判定は正規化後
event_form == ["publication"] のみ。books_media・source 名・title prefix では判定しない。
intentional-null 七欄は location_address / location_address_zh / location_address_en / business_hours / business_hours_zh / business_hours_en / location_prefectures とし、empty sentinel で保護する。
真實 DB 價格（is_paid / price_info / price_amount）は保持し、pure publication の UI / JSON-LD だけで隠す。価格欄、location_name、location_url は七欄の NULL / clear policy に含めない。organizer（publisher）は必須。
- sync 規則: 上記出版模板は
scraper/annotator.py::_PUBLICATION_SOURCES の白名單と双方向同期する。出版來源を追加・削除する時は source SKILL と annotator 白名單を同一変更で更新する。
- title prefix 規則: publication の title prefix は locale-aware にする。
name_ja/name_zh は [新刊出版]、name_en は [New Release]。期刊專文は name_ja=[雑誌記事]、name_zh=[期刊專文]、name_en=[Periodical Article] とし、[期刊專文] を日本語に流用しない。
- mixed negative:
['publication', 'lecture'] など physical form を含む rows は pure 扱いにしない。
- null-byte strip 必須: 全外部テキストに
.replace("\x00", "") を適用
tzinfo=timezone.utc: JST-aware datetime 禁止。datetime(y, m, d, tzinfo=timezone.utc) を使用name_ja_locked = True: 書名は NDL の確定値を保持するorganizer_type = ["government"]: 出版社ではなく NDL 登録機関扱い
既知の問題
- NDL ↔ hanmoto 重複: 同一書籍が両ソースに登場する場合がある（既知の非バグ、少量の重複は許容）
- 発売日が年/月のみ:
YYYY や YYYY-MM 形式は 1 月 1 日 / 月初として UTC midnight に正規化
- dc:identifier の形式: URN・URL 混在。末尾 8 桁以上の数字列を抽出して stable ID とする
