はじめに

Hypothes.isは、Webページ上にハイライトやコメントを付けられるオープンソースのアノテーションツールです。ブラウザ拡張やJavaScriptの埋め込みで手軽に使えますが、蓄積したアノテーションをバックアップしたい、あるいはTEI/XMLなど別の形式で活用したいケースもあります。

本記事では、Hypothes.is APIを使ってアノテーションをエクスポートし、TEI/XMLに変換する方法を紹介します。

APIキーの取得

  1. Hypothes.isにログイン
  2. Developer settings にアクセス
  3. 「Generate your API token」でAPIキーを生成

取得したキーを.envファイルに保存します。

c#p..eennvv.をe編x集aしmてpAlPeIキ.ーeをn設v定
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呼び出し

ddeefflewaauirrwonipprfeeiavtiilqqtd_h__p.h_pfgk=au=areaooeerrduentprtyfaludrtvhe("mr_lu(nllie=hs+lhlr)=(iifnt:=lein:enndotiabPneelpsp"bd.javikoo.s?.erst_i=n,sie:"rreohpne.nn/e(qn(alvet/+q"u._tfian,iauAel_h:nn=vrpueusof)edipoirsttai.lran.lth.dlasnior[hl.ousestonna"yiRrr(_rte[mHpbeilr_fi.ksYo.qzoe):pls.=Ptpuaps.(ipsNOhaetepp)nltoTersin.aeirnHssto(rr.tieE.e(nrees(p)Si.u"eant"(:Isur,qdta=)S/rl)(r"]_al)f)/t,Ape"a.s=PinBsd"w1I/cee.i)_{oarcet.KedreonhsEneesdv(tYd(rpe""r"pp:(#i]oa{)"pira))(nap)tmia}s_n")kdey"}="")inline:

全アノテーションの取得（ページネーション対応）

Search APIは1リクエストあたり最大200件なので、offsetをずらして全件取得します。

deffpualortaowrerslifeolfhetoelmfstlfitcfr_isua_sluhiatellaeeraor_l=nttntelfnaen==noslflpo==o+fu_sal=rt2rt=flael_oa00aeastntlaaft0pstlen_npiiiuiit=o+anilo_lomt=no_engtni<aantg[se[stptloae"t".tiiitttu=(teo_omai(s"oxtgnito"e[sttaestinpr]eaelt.osrialn:(en(odr"d"xs)f"c](st:i]hreel"eane,srd"uc(){lhr"t"eu[,ss"uer{lro"t"wu[:ss""eru]ros)"we:sr",u]s)"elri,mi"tl"i:milti"m:itl,im"iotf,fs"eotf"f:se0t}"):offset})

実行

#p#p#pyyyJtJt既tShSh存hOoOoJoNnNnSnのO+hみhNhy出yかyTp力pらpEooToIttEt/hhIhXee/eMssXsL__M_eeLeをxx変x出pp換p力ooのorrみrttt...pppyyy--jtseoin--oonnllyy
UTSSsoaaetvvraee:ldd:aJTc6SEcOItaN/:n:XynMoooLutu:rat_tpouiuusotten/prsaunntanmaetn@anhtoyitpoaonttsih.oejnsss.o.inxsm(l6annotations)

アノテーションのデータ構造

エクスポートされたJSONの各アノテーションは、W3C Web Annotation Data Modelに基づいた構造を持っています。

{}"""""""]icuutttdrsreaa{}"eeixgr:ar"tsg""]t":""ess"e:::toe{}{}{}ad""ul,,1""h"[:re""""""""""""l:atこ"cctsseetsetepsBctれメ[etyttnnytnyxruU"cpはモ"opaaddpadpaefh2ts正":rerrCOer"ecffP0::し]""ttof"t:"tiid2yい,"::COnf:":"xxE6/？hofts:1:""f-ue"t["nfae"6"::G0rx,tRtsitT16T"-2_apaaen"e67e此""L-umsnite:x6x詩人宋k2sp:gn"rt3t乃樂太87el/ee:"0P,Q是太祖iTre/Sr:ou"平朝V1n.ee"3so,無中73acxl:3"it事一G:moae5/te日個T0emmc",miS　名38@/ptaoe　儒w:hplminl　姓"3yaeranSe鶯邵,3pg."i[ec花諱.oec,n1lt無尭4t"o[]eo限堯2h,m1/cr日夫7e/]dt"高道7sp/io,眠號7.advr康2igi["\節+sev1,n先0""[]　生0,,1/　所:]p　作0/[　為0p1　""[]　,1/　]s　"p",a,n[4]",

3種類のセレクタ

Hypothes.isは、アノテーション対象のテキスト位置を3種類のセレクタで記録しています。

セレクタ仕組み頑健性
RangeSelectorDOM上のXPathで位置を指定△ HTML構造の変更に弱い
TextPositionSelector文字のオフセット位置で指定△ テキストの増減でズレる
TextQuoteSelector対象テキスト＋前後の文脈で指定◎ fuzzy matchで再アンカリング可能

元文書が変更された場合、Hypothes.isはこれらのセレクタをフォールバックとして順に試みます。TextQuoteSelectorはprefix/suffixを含むfuzzy matchを行うため最も頑健ですが、対象テキスト自体が削除・大幅変更された場合はアノテーションが「orphaned（孤立）」状態になります。

TEI/XMLへの変換

エクスポートしたJSONをTEI/XML形式に変換します。

マッピング方針

Hypothes.isTEI/XML
対象文書（URI・タイトル）<sourceDesc><bibl>
文書ごとのグループ<div>
各アノテーション<ab>
ハイライトテキスト（TextQuoteSelector.exact）<quote>
コメント本文<note type="annotation">
タグ<note type="tag">

変換ロジック

TextQuoteSelectorから引用テキストを抽出し、TEI要素にマッピングします。

defg"fre"oet"rt_TutetfrexaonxtrrtQgN_uesioqotefnutleoeistSniereenle(la.taentguncnaerntortnootg(trae"saかtttetらi.ylieogpoxneena.t")cg():te"/ts=p(e=r"lete"facTirtexgox/ertst"Qu",uf,of[ti[]ex])Sを):e取:l得e"c"t"or":

アノテーションをURIごとにグループ化し、<div> → <ab> → <quote> / <note> の構造で出力します。詳細はソースコードを参照してください。

出力例

<<?T/xE<<TmIt/t/Ele<te<tIxif/exb/e>vmHi<<<fito<bxelelt/p/s/iH>dd/otrnaei<tu<po<sleyi<<dd>ssdDttibpuub/oea>vha/iyi=eelitl>bri<<buDdeb<<av>o"rsetliElcbtrireecaqn/b>nh>cSlecxieliebcsrodxuoこn>=t>teSapcDtflec>r>motれo"tm>ttoaexl>D>r巻lteはt1ptHmirtsmetee首:e正e.:>ytoticl>ass題i>tcwし>0/p>neo>:巻rcp：d此yohい"/oSdni首g>=新=詩pre？wttSd題e"刻"乃ernewhmft=：t#全a是=e=nwetrm"新=s像n<"s"c.s>ots刻"r水n/ap2ot.m>r全hc滸-qn=0deic像t-傳aun"2iisH-水t0<1ooh6n-y0滸p"/lttt-gcAp"傳s>hBeat0=.no><:eU>tp2"ont//ahis-Uroht/dPo:2Tgteie>dn/7F/astxE"/T-nt.lafh18siiemGy3"/os>p"p:?1nl>o0>.sAet80P.h:"EIce3>x<os3p/m..op/i4r>ps2ta/7<ga7/e/7t"a2i>1+thl0ltB0etU:>ph0sP0:d"/E>/feGx"ample.com/page</ref>

元文書の変更とアノテーションの整合性

Hypothes.isのアノテーションは「スタンドオフ注釈」方式で、元文書とは別に保存されます。そのため、元文書が変更されるとアノテーションの位置がズレる可能性があります。

  • 軽微な変更 : TextQuoteSelectorのfuzzy matchにより再アンカリングされることが多い
  • 大幅な変更 : アノテーションが「orphaned」状態になり、対象箇所に紐づかなくなる

TEI/XMLにエクスポートしておけば、<quote>要素にハイライト対象テキストが記録されるため、元文書との対応関係は少なくとも記録として残ります。

まとめ

  • Hypothes.is APIを使えば、自分のアノテーションをプログラムから取得できる
  • TextQuoteSelectorのexact/prefix/suffixが、アノテーション対象テキストの特定に最も重要
  • TEI/XMLへの変換により、人文学研究で広く使われるフォーマットで保存・活用できる
  • ただし元文書の変更によるアンカリングのズレには注意が必要

ソースコードはGitHubで公開しています。