gBizINFO で会社情報を肉付けする前に「充足率」を測れ——資本金も設立日も、中小の大半は空で返る

法人番号を手がかりに、会社の資本金・設立日・従業員数を公的APIで補完したい——という場面は多い。gBizINFO の基本APIはその定番だが、数万件を叩き始める前に 300 件だけサンプルを取って充足率を測っておくと、無駄打ちと過剰な期待を同時に潰せる。

事象

gBizINFO の基本API（/hojin/v1/hojin/{法人番号}、トークンはリクエストヘッダ X-hojinInfo-api-token）は、存在する法人番号ならまず 200 を返す。だが返ってきた JSON を開くと、資本金・設立日・従業員数といった「欲しかった項目」が 空のまま のことが多い。エラーではない。値が無いだけだ。

中小法人だけを母集団にして実測すると、資本金・設立日・従業員数の いずれか一つでも埋まっている法人は 1 割前後 にとどまった。9 割近くは、法人番号と商号・所在地くらいしか返ってこない。

さらに、期待していた「社会保険の加入状況」は、基本APIのレスポンスに フィールド自体が存在しない。空で返るのではなく、そもそも項目が無い。

原因

gBizINFO のリッチな項目（資本金・設立日・従業員数・補助金・調達・各種認定など）は、政府と接点を持った法人ほど埋まる 構造になっている。補助金の交付、入札への参加、経営革新等の認定——こうしたイベントを通じてデータが集まる。だから調達や補助金の実績がある法人は厚く、そういう接点を持たない大多数の中小法人は薄い。

母集団を「中小法人だけ」に絞ると、この偏りがまともに効く。上場企業や官公需の常連を含む母集団なら充足率はもっと高く見えるが、無名の中小だけを引くと 1 割前後まで落ちる。

解決策

本番の一括処理を走らせる前に、300 件のサンプルで充足率を測る。 対象の母集団からランダムに 300 件抜き、基本APIを叩いて、各フィールドが「非空で返った率」を数えるだけでいい。

const FIELDS = ["capital_stock", "date_of_establishment", "employee_number"];
const counts = Object.fromEntries(FIELDS.map((f) => [f, 0]));
let anyRich = 0;

for (const num of sample300) {
  const res = await fetch(`https://info.gbiz.go.jp/hojin/v1/hojin/${num}`, {
    headers: { "X-hojinInfo-api-token": TOKEN },
  });
  if (!res.ok) continue;
  const info = (await res.json())["hojin-infos"]?.[0] ?? {};
  let rich = false;
  for (const f of FIELDS) {
    if (info[f] != null && info[f] !== "") { counts[f]++; rich = true; }
  }
  if (rich) anyRich++;
}
// counts と anyRich/300 を見てから、数万件を叩くか決める

この 300 件が返す数字を見てから、本番を回すか・別ソースを併用するか・そもそも肉付けを諦めるかを決める。充足率が 1 割なら、数万件叩いても 9 割は空振りだと事前にわかる。

補足

• フィールド名は capital_stock（資本金）／date_of_establishment（設立日）／employee_number（従業員数）。null または空文字で「値なし」を表すので、0 や false と混同しないよう非空判定で数える
• 社会保険の加入情報が要るなら、基本APIには無いので別系統のデータを当たる必要がある。基本APIのレスポンスを何度見てもフィールドは現れない
• 公的APIを使った補完は「叩けば埋まる」と期待しがちだが、埋まるかどうかは相手のデータ構造次第だ。数万件のループを書く前に、小さなサンプルで充足率を測る一手間が、丸一日の空振りを防ぐ