検証できるバウンディングボックスを返すOCR API

バウンディングボックスは、OCRを検証するための手がかりです。素の文字列は、モデルが何を読んだつもりかを示すだけ。一方ボックスは、それをページ上のどこで読んだのかまで示してくれるので、あなた（あるいはレビュー担当者やコード）は、その値を鵜呑みにせず原本と突き合わせて確認できます。請求書、経費、KYC、記録管理といった監査の対象になる場面にOCRを組み込むなら、「モデルが total: 2,045 を返した」だけでは足りません。その 2,045 がどのピクセルから来たのかを指し示せる必要があります。

幸い、主要なOCR APIのほとんどはバウンディングボックスを返してくれます。やっかいなのは、いざ実装を始めると効いてくる3つの点で各社が違うことです。すなわち座標系、（生テキストだけでなく）構造化フィールドまで得られるか、そしてボックスの隣に付く値ごとの信号が実際には何なのか、の3つです。本ガイドではこの3点を順に解説し、座標が明示的な確認契約——値ごとの判定と、確認すべきパスの一覧——とともに返るOCR APIが、実際にどんなものかをお見せします。

ほとんどのOCR APIはボックスを返す——違いはここにある

Google Cloud Vision、Tesseract、Amazon Textract、Azure AI Document Intelligence は、いずれもテキストと一緒にジオメトリ（形状情報）を返します。違いが出るのは、座標系、構造化フィールドまで得られるのか生テキスト＋レイアウトだけなのか、そして値ごとの数値が何を報告しているのか、という点です。下表は2026年8月時点の各社の公開ドキュメントをまとめたものです。仕様は動きますので、統合工数を見積もる前に最新のドキュメントで再確認してください。

注目したい点が2つあります。1つめは、座標の単位は使い回せないこと。ピクセルのボックスは実際に読み取られた画像そのものに紐づきますが、正規化されたボックスはリサイズしても有効なままです。2つめは、値ごとの列が同じものを測っているとは限らないこと。認識信頼度が答えるのは「エンジンが自分の読み取りにどれだけ自信があるか」で、「返ってきた値がそもそもページ上で見つかったのか」とは別の問いです。

space-ocr が値ごとに返すもの

業務データは data.values に、リクエストしたスキーマそのままの形で入ります。その値がどこから来て、検査を通ったのかは、同じパスをキーにした別のマップ data.cells にまとまります——total、明細行なら items[0].price といったパスです。各セルが持つのは次のものです。

• box — 0〜1000で正規化されたグリッド上の、整数からなる軸並行矩形 { xmin, ymin, xmax, ymax }（0,0 = 左上、1000,1000 = 右下）。画像のピクセルサイズに依存しません。
• quad — 書類の傾きに沿った回転対応ボックスを形作る、順序付きの4点（左上、右上、右下、左下）。傾いたスマホ写真でもきれいに枠が付きます。box と必ず一緒に返ります。
• verified — 判定であり、review の鏡です。何かが立てば false、何も立たず照合が実際に走ったなら true、何も立たないが照合する相手が無かったとき（行のユニオンなど）は null です。
• review — null、または { reasons }。理由はランキング順で、先頭が代表です。コードには text_mismatch、low_ratio、nobox、missing などがあります。
• evidence — 判定の生データです。text_match（文字照合そのもの）、source（vision_symbol_match、token_id）、match_ratio、そしてその座標でOCRが読んだ文字である printed_text が入ります。

同じパスは data.review.flagged にも並びます。これが確認リストで、目を通すべき値ごとに1件、理由付きで載ります。data.image は実際に読み取られたページの幅と高さで、すべての座標はこれを基準に表されます。（スカラー型の type、あるいは string フィールドへの pattern・enum を宣言すると data.normalized の層も付きますが、下の string だけの例では現れません。）

ピクセルか、正規化か？一度変換しておけば、リサイズで崩れなくなる

OCR統合でよく起きるバグの1つが、ピクセル座標がアップロードした画像そのものに紐づいてしまうことです。保存のためにリサイズや再圧縮をしたり、EXIFの回転フラグを見落としたりすると、重ねたボックスがずれたり、切れたり、別のテキストに乗ったりします。正規化座標なら、この手のバグをまるごと避けられます。0〜1000のボックスは、同じページをどう描画しても、その上にそのまま当てはまるからです。

先に押さえておきたいのは、基準となる面が data.image であって、送ったファイルそのものではない、という点です。これは実際に読み取られたページで、EXIFの向きはすでにピクセルに焼き込まれ、大きな写真は読み取り前に縮小されています。そのため width と height はアップロードした画像と入れ替わって返ることがあります（4000×3000で送って3000×4000が返る、など）。data.image を基準に変換すれば計算は合います。

表示中の画像にボックスを描くときは、一度だけ変換します。

• SVGオーバーレイ — SVGに viewBox="0 0 1000 1000" を与え、box や quad をそのまま描きます。
• 絶対配置のdiv — leftPct = xmin / 1000 * 100、topPct = ymin / 1000 * 100、widthPct = (xmax - xmin) / 1000 * 100、heightPct = (ymax - ymin) / 1000 * 100。
• ピクセルへ戻す — pixel_x = box.xmin / 1000 * data.image.width、pixel_y = box.ymin / 1000 * data.image.height。

EXIFの向きはそのページに適用済みなので、回転したスマホ写真（向き 6/8）でも、あなたの側で補正処理をかける必要はありません。ただし傾きの補正（デスキュー）は行いません。傾いた写真は傾いたままなので、quad が傾きに沿い、box はその周りで軸に並行なままになります。

信頼度スコア、マッチ率、そして判定

ここは押さえておく価値のある区別です。ほとんどのOCR APIが用意しているのは認識信頼度で、これはフォントの鮮明さや画質などをもとに、エンジンが自分の読み取りにどれだけ自信があるかを表す数値です。役には立ちますが、いわばモデルが自分の答案を自分で採点しているようなもの。これに対してマッチ率は、外側の事実を測ります。モデルが返した値の文字のうち、ページ全体のOCRが検出したシンボルの中で実際に見つかったのは何文字か、です。値は十分な認識信頼度を付けて返ってきても、ページ上の何にも一致しないことがあり得ます。

とはいえ、この比率を渡されて「しきい値は自分で決めてください」と言われるわけではありません。match_ratio は判定の根拠として evidence に入っています。しきい値はエンジン側が当てており——0.85以上で確実な文字一致として扱われます——カバレッジが足りなければ、そのセルは review の理由に low_ratio を付けて返ります。したがってコード側のゲートは review != null、より良いのは data.review.flagged をそのまま回すことです。そうすれば、比率では見えないクラスにも届きます。required なのに一度も返らなかった値（missing）、座標が付かなかった値（nobox）、宣言したパターンや範囲を破った値、などです。

意外に思われがちですが、驚く必要のない組み合わせが1つあります。verified: false と evidence.text_match: true の同居です。これは文字としてはページと一致していて、あなたが宣言したルールの方が引っ掛けた値です。どちらも理由は違えど確認に値します。そして、どちらも逆側を保証するものではありません——2つのエンジンが同じ誤読で一致してしまうこともあるからです。

検証したら、OCRを再実行せずにクエリする

座標は、データが残り続けてこそいちばん役立ちます。POST /upload で画像をシートに投入し、あとは GET /view でサーバー側からクエリするだけです。where、sort、select、limit、offset を使って、たとえば total >= 40000 の行をまとめて取り出す、といった操作が、OCRの再実行も追加課金もなしに行えます。絞り込みの対象になるのはそのシートの列（ほかに name、ocrStatus、createdAt）で、各行は cells マップを保ったまま返るので box と quad もそのままです。boxes=0 を付ければ外して軽いペイロードにもできます。検証ワークフローの詳しい解説は、バウンディングボックスによるOCRの検証とOCR監査証跡をご覧ください。

APIから検証可能なバウンディングボックスを得る手順