V2のsourceは何を意味するのか
sourceフィールドは、最終的な結果を生んだ経路を示します。保存されたデータセットの検索、AIによる推定、または選ばれたソースなしのいずれかです。データセットの元の公開者の出典でも、ライセンスの証明でも、推定が正しいことの保証でもありません。
このガイドでは、現在のV2のレスポンスの仕様と、GenderAPI.io自身がまとめたデータベース概要を説明します。以下のデータベースの観測は、測定した件数の一覧と整合性の確認です。レビュー済みの元データのソース一覧と、独立した精度のベンチマークはまだ公開していません。
| source | 分かること | 証明されないこと |
|---|---|---|
dataset | 保存されたレコードが選ばれました。件数が完全に同数の場合は、性別が不明になることがあります | 元の公開者、収集方法、ライセンス、レコードの古さ、観測の独立性 |
ai | 最終的なレスポンスは、設定されたAIの推定経路から得られました。性別がnullになることもあります | 数えられたサンプル、データセットの出典、較正された推定の精度 |
none | データセットのみの最終結果で、保存されたレコードは選ばれませんでした | その入力が、どの集団や言語でも名前と結び付かないこと |
データベース概要：2026年9月26日
コレクションのメタデータは2026-09-26T15:28:18.227Zに、無作為のサンプルは2026-09-26T15:31:54.045Zに読み取りました。どちらの件数も、それぞれのコレクションのMongoDB collStatsのメタデータから得たもので、別途すべてを数え直したものではありません。一般のコレクションには名前のレコードが、国別のコレクションには名前と国の組み合わせのレコードが保存されています。この2つの件数を足して、一意の名前や一意の人の総数としないでください。
MongoDBは各コレクションから5,000件のドキュメントを無作為に抽出し、データベースサーバー上で以下の集計チェックを行いました。公開する報告には、名前や元のレコードは含まれていません。これはGenderAPI.ioが本番のデータベースについて行った観測であり、独立した監査でも、固定された評価用データセットでもありません。これらの確認は件数の整合性を見るもので、推定の精度、一意の人や名前の数、APIのカバレッジを示すものではありません。
| 観測項目 | 一般のレコード | 国別のレコード |
|---|---|---|
| コレクション | general | country-specific |
| メタデータ上のドキュメント数 | 2,483,220 | 4,080,692 |
| 保存されている一意のキー | name | name + country |
| 無作為に抽出したドキュメント | 5,000 | 5,000 |
| サンプル中で数値ルールを満たさなかった件数 | 0 | 0 |
| サンプル中でmale + femaleがtotalと異なる件数 | 0 | 0 |
| サンプル中でmaleとfemaleの件数が同数の件数 | 124 | 94 |
| サンプル中でupdated_atフィールドがある件数 | 667 / 5,000 | 741 / 5,000 |
データベースの確認で分かること
数値のチェックでは、totalが正の安全な整数であり、maleとfemaleの件数が有限でゼロからtotalの範囲にあることを求めます。別のチェックでは、male + femaleとtotalを比較します。抽出したすべての件数がこれらのチェックを通過しましたが、コレクション内のすべてのレコードが整合していることや、ある推定が正しいことを示すものではありません。
maleとfemaleの件数が同数だった行は、一般のコレクションのサンプルで124件、国別のコレクションのサンプルで94件でした。これは保存された件数が同じだというだけで、独立して検証された判断のつかない性自認でも、APIの不明率でもありません。実際のAPIの結果は、入力、Redisの可用性、候補の選び方、AIの設定によって決まります。
2026-09-26T15:33:13.811Zに一般のコレクションのcountryフィールドを別途集計したところ、244種類の保存値が見つかりました。そのうち239種類は大文字2文字の形式で、5種類はそれ以外の形式でした。ISOへの準拠、国別のレコードの分布、対応国のカバレッジは測定していません。これらの数字は、対応している国の数ではありません。
2つのサンプルのどちらにも、ソースやライセンスのフィールドはありませんでした。これは、すべてのレコードや外部のシステムに出所の情報がないことを示すものではありません。フィールドの有無は、ソースのライセンスの状況を証明しません。一部のレコードには数値のupdated_atフィールドがありましたが、その値と意味は確認していません。データの新しさや更新のスケジュールを示すものではありません。
V2はデータセットの検索をRedisから提供しています。2026年9月26日、GenderAPI.ioはシステムの管理者として、MongoDBとRedisに同じデータセットが入っていることを確認しました。この一致はその確認に基づくもので、2つのデータベースを独立して比較したわけではなく、その検証はまだ完了していません。上の集計は保存されたレコードについてのもので、APIの回答カバレッジは、送信された入力、候補の照合、AIの設定にも左右されます。サンプルは固定のシードを使わずに抽出し、固定したスナップショットなしで読み取り、独立した参照ラベルもありません。そのため、推定の精度、較正、回答カバレッジは測定できません。
レスポンスで根拠をたどる
| フィールド | 意味 | 限界 |
|---|---|---|
input | 入力の種類、値、指定された国のコンテキストをそのまま返します | 入力値は、独立して検証された本人の情報ではありません |
match.name / match.method | 選ばれた検索の候補と、それが正規化、トークン分割、部分文字列の抽出、モデルによる推定のどれで得られたかを示します | トークンが一致しても、フルネームやハンドル名から本当の名が切り出されたとは限りません |
match.scope / match.country | 選ばれた保存済みの行が、国別の検索とグローバルの検索のどちらによるものかを示します | 国を指定しても、国別の行があるとは限りません |
sample_count | 選ばれた行に保存されている合計件数。AIによる推定ではnull | 一意の人数、独立して抽出された観測、精度評価のサイズを表すとは限りません |
confidence / confidence_kind | 保存された件数から計算した比率と、モデルが報告したスコアを区別します | どちらの値も、個人の性自認についての較正済みの確率ではありません |
country / country_source | 返されたレコードの国のメタデータ、またはAIによる名前との関連付け（ある場合） | 国籍、居住地、検証された出身ではなく、入力した国が照合されたことの証明でもありません |
入力の照合が結果に与える影響
データセットの検索では、テキストを正規化して候補のトークンを取り出します。メールアドレスの場合はローカル部分から候補を作り、ユーザー名の場合は先頭にある任意の@を取り除きます。通常のメールアドレスとユーザー名の検索では、範囲を限定した部分文字列の候補も試すことがあります。候補のレコードが複数ある場合は、保存されている合計件数が最も多いレコードが選ばれます。そのため、意図した名とは別のトークンが選ばれることがあります。
国のコンテキストが指定されている場合、検索では候補ごとに国別の行を試し、国別の行がなければグローバルの行を使います。最終的な結果には、選ばれた照合結果が示されます。同数で判断できない国別の行が、その候補のグローバルの行に自動的に置き換えられることはありません。
通常のAIのプロンプトは、名として認識できる名前を求めます。forceToGenderizeを使うと、個人のニックネームやエイリアスとの関連付けも許可されるため、このモードではname: nullのままnullでない性別が返ることがあります。これらは別の推定タスクであり、個別に評価する必要があります。
データセットの検索とAIによる処理
AIが呼び出されると、V2は送信されたtype、value、国のコンテキストを、設定されたAIの推定サービスに送ります。メールアドレスの場合、プロンプトはドメインと+以降のサフィックスを無視するようモデルに指示しますが、AIで処理する前にそれらの文字が値から取り除かれることを約束するものではありません。ワークフローでデータセットのみの推定が必要な場合は、forceToGenderizeを使わずにai_mode: offを使用してください。
AIのレスポンスの検証では、JSONのフィールド、型、フィールド間の整合性を確認します。返された名前、性別との関連付け、国との関連付けが事実として正しいことを証明するものではありません。公開される結果には、モデルの識別子やバージョン、推定の出典は含まれません。
| オプション | 推定の経路 | 返される根拠 |
|---|---|---|
| ai_mode: off | データセットの検索のみを使います | 選ばれたデータセットのメタデータ、または選ばれたレコードのない不明な結果 |
| ai_mode: fallback | まずデータセットを試し、性別が返らなければAIを呼び出します | 最終的な経路の根拠。データセットとAIを合わせたサンプルではありません |
| ai_mode: always | 設定されたAIの推定経路を直接使います | モデルが報告したスコア、または信頼度がnullの不明な結果。sample_countは常にnull |
| forceToGenderize: true | データセットを試し、推定できなければニックネームに対応したAIを使います | データセットの根拠、またはモデルが報告したエイリアスとの関連付け。nameはnullになることがあります |
まだ公開されていないソースのドキュメント
レビュー済みのソース一覧は、ここでは公開していません。レスポンスの仕様と実装の動作だけでは、データの出所、ソースの利用許諾、代表性、ラベルの品質を検証できません。ソースごとの説明をする前に、次の根拠を記録し、レビューする必要があります。
このドキュメントのレビューは、元のソースがライセンスを受けているかどうか、完全かどうかを判断するものではありません。公開されている根拠の限界を示すものです。用途にソースごとの評価が必要な場合は、GenderAPI.ioにお問い合わせください。
| 根拠 | 必要な記録 | 公開の状況 |
|---|---|---|
| 出所と利用許諾 | ソースまたは公開者の名称、収集期間、ライセンス、その他の記録された利用の根拠 | レビュー済みの一覧は、ここでは公開していません |
| 処理の履歴 | 変換、正規化、重複の除去、集計、合成データやモデルが生成したデータの寄与 | source: datasetのラベルからは分かりません |
| 集団のカバレッジ | 国と文字体系のカバレッジ、選定の手順、ラベルの定義、記録された偏り | 独立して評価したカバレッジの数値は、ここでは公開していません |
| データの新しさ | スナップショットの識別子、ソースごとの更新日、対応する更新のスケジュール | V2のレスポンスには、レコードごとの新しさやスナップショットの識別子は含まれません |
| 品質と訂正 | 検証の結果、重複の確認、訂正と削除の扱い、レビューの責任 | ソースごとの監査結果は、ここでは公開していません |
プライバシー、処理、責任ある利用
ソースの出所、個人データの取り扱い、法的な条件は、それぞれ別の問題です。処理における役割、保持、プロバイダー、契約上の条件については、現在公開されているポリシーを確認してください。この技術ガイドは、新たな保持の約束を加えるものでも、法令への準拠を証明するものでもありません。
ワークフローに必要な情報だけを送信してください。信頼度の種類と不明な結果を保持し、推定をその人の自己申告の性別として説明しないでください。推定された性別を、個人に重大な影響を与える判断の根拠にしないでください。
精度の根拠と改訂履歴
ソースのラベルが示すのは推定の経路であり、測定された品質ではありません。レスポンスのスコア、回答カバレッジ、エラー、再現可能な評価に必要な情報の違いは、精度のガイドで確認してください。
| 日付 | ドキュメントのリビジョン | 変更内容 |
|---|---|---|
| 2026-09-29 | 1.0.0 | 日付付きのMongoDBの集計、サンプルの整合性の確認、V2のsourceとmatchのフィールド、AIによる処理の範囲、ソース一覧の残る課題についての日本語版。MongoDBとRedisの一致は、2026年9月26日のGenderAPI.ioによる確認に基づくもので、独立した比較はまだ完了していません。精度の割合やソースのライセンスについての主張は追加していません。 |