名前から性別を推定するAPI：実装ガイド

名前から性別を推定するAPIは、氏名データに見られる統計的な傾向を返します。本人の性自認を確認する仕組みではありません。集計や低リスクなデータ分析には利用できますが、個人に関する重要な判断には使えません。

NameGenderは gender だけでなく、probability、sample_size、confidence、source を返します。実装側は、この根拠を見て結果を採用するか、確認対象にするか、null のまま保持するかを決められます。

最初のAPIリクエスト

APIキーを作成し、Authorization: Bearer ヘッダーで送信します。漢字やかなを扱う場合は、URLエンコードが不要なPOST形式が扱いやすい方法です。

curl -X POST https://namegender.com/api/v1/gender \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"さくら","country":"JP"}'

レスポンスの基本形は次のとおりです。

{
  "query": "さくら",
  "name": "さくら",
  "gender": "female",
  "probability": 95,
  "sample_size": 0,
  "confidence": "unverified",
  "country": "JP",
  "source": "script",
  "matched_as": "sakura"
}

sample_size: 0 は、結果が必ず誤りという意味ではありません。件数を監査できる公的な登録統計がなく、割合や記録の存在だけが根拠であることを示します。この場合、confidence は unverified になります。

レスポンスで保存すべき項目

フィールド	実装上の意味
`gender`	閾値を満たした主要カテゴリ。根拠が弱い場合は `null`
`probability`	データ上の主要カテゴリの比率。本人についての確率ではない
`sample_size`	結果を支える集計可能な人数
`confidence`	証拠量に基づく信頼区分
`source`	データベース、文字規則、あいまい一致、LLM、該当なし
`name`	前処理後に実際に照合された名前

gender だけを保存すると、強い結果とほぼ半々の結果を区別できません。後で閾値を変更できるように、根拠フィールドも保存してください。

日本人名で先に決めること

日本人名には漢字、ひらがな、カタカナ、ローマ字が混在します。また、日本語順では姓が先です。入力欄が姓と名に分かれているなら、名だけをAPIへ渡すのが最も安全です。

フルネームしかない場合は、次の情報を保持します。

元の文字列
姓名の順序
読み仮名またはローマ字があるか
APIが実際に照合した name

漢字だけでは読みが一意に決まらないため、読み仮名が保存されているシステムでは、かなまたは確認済みのローマ字を使う方が誤読を減らせます。

一括性別判定

複数の氏名は、1件ずつ呼び出さず一括エンドポイントへ送信できます。結果は入力順で返ります。

curl -X POST https://namegender.com/api/v1/gender/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"names":["太郎","花子","さくら","Yuki"],"country":"JP"}'

本番処理では、高信頼、要確認、未知の3つに分けてください。未知を自動的に多数派へ置き換えると、見かけのカバレッジは上がりますが、誤分類を監査できなくなります。

利用してはいけない場面

名前による推定は、採用、医療、金融、保険、法律、本人確認、利用資格の判断に使用しないでください。誤りが個人へ影響する処理では、本人に確認する方法が必要です。

パラメータ、認証、エラー形式は日本語APIドキュメントで確認できます。導入前には、自社データから正解ラベル付きの小さな検証セットを作り、文字種ごとに測定してください。