Hypothes.is APIでWebアノテーションをエクスポートしてTEI/XMLに変換する
はじめに Hypothes.isは、Webページ上にハイライトやコメントを付けられるオープンソースのアノテーションツールです。ブラウザ拡張やJavaScriptの埋め込みで手軽に使えますが、蓄積したアノテーションをバックアップしたい、あるいはTEI/XMLなど別の形式で活用したいケースもあります。 本記事では、Hypothes.is APIを使ってアノテーションをエクスポートし、TEI/XMLに変換する方法を紹介します。 APIキーの取得 Hypothes.isにログイン Developer settings にアクセス 「Generate your API token」でAPIキーを生成 取得したキーを.envファイルに保存します。 cp .env.example .env # .env を編集してAPIキーを設定 HYPOTHESIS_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx アノテーションのエクスポート APIの基本 Hypothes.is APIのベースURLは https://api.hypothes.is/api です。認証はAuthorization: Bearer <API_KEY>ヘッダーで行います。 主要なエンドポイント: エンドポイント 用途 GET /api/profile 認証ユーザーのプロフィール取得 GET /api/search アノテーション検索 GET /api/annotations/{id} 個別アノテーション取得 スクリプト エクスポートからTEI/XML変換までを1つのスクリプト hypothes_export.py にまとめています。 https://github.com/nakamura196/hypothes-export/blob/main/hypothes_export.py 以下、主要な処理を抜粋して説明します。 .envの読み込みとAPI呼び出し def load_env(): env_path = Path(__file__).parent / ".env" with open(env_path) as f: for line in f: line = line.strip() if line and not line.startswith("#") and "=" in line: k, v = line.split("=", 1) os.environ[k.strip()] = v.strip() def api_get(endpoint, params=None): api_key = os.environ["HYPOTHESIS_API_KEY"] url = f"https://api.hypothes.is/api/{endpoint}" if params: url += "?" + urllib.parse.urlencode(params) req = urllib.request.Request(url) req.add_header("Authorization", f"Bearer {api_key}") with urllib.request.urlopen(req) as resp: return json.loads(resp.read().decode()) 全アノテーションの取得（ページネーション対応） Search APIは1リクエストあたり最大200件なので、offsetをずらして全件取得します。 ...