フルネームを名と姓に分割する
結合された名前フィールド 1 つ、API 呼び出し 1 回、きれいなフィールド 2 つ——手書きの分割処理が壊れる原因になる前置詞、敬称、逆順はすでに処理済みで、性別も同じレスポンスに入っています
結論
- 結合されたフィールドを送ると first_name と last_name が返ります——さらに性別、精度、サンプル数も、同じレスポンスで、1 credit で
- 前置詞（「van der」「von den」「de la」）や学位・職位の肩書きは、つまずきの原因ではなく処理対象です——逆順の「Rossi, Andrea」も解決されます。カンマからではなく名前データからです
- どちらの半分もどちらにもなり得る場合、判断は各部分が名として現れる頻度と姓として現れる頻度の比較から来ます——文字列内の位置からではありません
- strict mode は、姓がデータベースにないときに推測ではなく空の姓を返すので、欠落が見えます
スペースでの分割がうまくいかない理由
ほとんどのコードベースにこの一種があります。名前フィールドを取り、空白で分割し、最初の要素が名、最後の要素が姓。テストデータが英語なのでレビューを通り、英語でない最初の顧客で静かに壊れます
高くつくのは失敗のしかたです。例外はどこにも出ません。姓が「van」の人だらけのデータベースと、そう呼びかける一斉配信と、原因を指すログ 1 行もない状態が残ります
分割を決めるもの
4 つのことが、この順序で働きます——そして最後の 1 つは規則ベースの分割処理には持ちえないものです。名前が実際にどう分布しているかを知る必要があるからです
- まず肩書きを外します。「Prof. Dr.」「Dipl.-Ing.」「Managing Director」など、保守されたリストにあるものは、ほかの何かが決まる前に取り除かれるので、名前フィールドに入り込むことはありません
- 前置詞は姓とともに残ります。「van」「van der」「van den」「von」「von der」「de」「de la」「du」「le」「di」「des」およびその近縁は、属する姓の一部として認識されます
- 順序を句読点に任せません。「Rossi, Andrea」のカンマは敬称と一緒に取り除かれ、順序はそのあと名前データから読み取られます——カンマは書式の習慣であり、多くのリストが一貫せずに使っています。CSV と Excel のアップロードでは代わりに列の順序を指定でき、指定された順序は指定どおりに使われます
- 曖昧さはデータが決めます。候補となる各部分は名のデータベースと姓のデータベースの両方で照会され、名よりも明らかに姓らしく振る舞う部分が姓になります
国コードを渡すと、同じ比較がすべての国に対してではなくその国に対して行われます——リストの出所がすでにわかっているときに望ましい動きです
呼び出し方
これを行うエンドポイントは 2 つあり、どちらを使うかは strict mode が必要かどうかで決まります
v2 — 現行の API
POST https://gender-api.com/v2/gender/by-full-name
{ "full_name": "Anna van der Berg", "country": "NL" }{
"result_found": true,
"first_name": "Anna",
"last_name": "van der Berg",
"gender": "female",
"probability": 0.98,
"details": { "credits_used": 1, "samples": 8961, "duration": "33ms" }
}v1 — strict mode が必要な場合
strict mode は v1 の分割エンドポイントにのみ存在します。新しい API を使うことより空の姓が返ることのほうが大事なら、こちらを使ってください
GET https://gender-api.com/get?split=Anna%20van%20der%20Berg&strict=true&key=…- v2 フルネームリファレンス — フィールド、エラー、OpenAPI の記述
- v1 分割リファレンス — strict パラメータとその正確なレスポンス
- PHP、Python、Node、Java、Go、Ruby、Rust、Perl、.NET 向けの公式クライアント
まず、その列はそもそもフルネームですか？
自分が作ったのではないファイルを処理する前に知っておく価値があります。最大 100 件の値のサンプルを送れば、フルネームらしいかどうかが返ります——credits はかかりません
POST https://gender-api.com/v2/name-format-detect
{ "names": ["Sophie Jones", "Lorenzo Carlos", "Anna van der Berg"] }{
"is_fullname": true,
"fullname_probability": 1,
"validHints": [ … ]
}これが何を測るのかをはっきりさせておきましょう。fullname_probability は送った値のうち 2 語以上でできているものの割合で、is_fullname はその割合が 0.6 を超えているかどうかです。列についての判断であり、個々の名前についての判断ではありません——そもそも分割すべきかを決めるときに必要なのはまさにこれで、分割そのものの代わりにはなりません
混在した列も正当な答えです。リストによっては「Thomas」と「John Smith」が並んでいることがあり、分割処理は事前に並べ替えなくても両方に対応します
まだお客様の手が必要なところ
世界中のあらゆる名前に対応できると言う分割処理があれば、それは嘘です。以下は、どんな規則でも文字列だけからは解決できないケースです
フォームを自分で管理しているなら、いちばん安い解決策は API ではありません。1 つのフィールドの代わりに 2 つにするか、形式が「名、姓」であることを示すことです。以下はすべて、フォームを管理していない場合の話です
- 姓が先の形式。カンマがあるかどうかに関わらず、名前データが支持する読み方が位置の規則に勝ちます——誤るよりはるかに多く正しいのですが、保証ではありません。列全体が姓が先だとわかっているなら、句読点に頼るのではなくアップロード時にそう指定してください
- 1 語だけの名前。単一名には見つけるべき姓がありません。名を途中で切るのではなく、姓が空で返ります
- 一貫しない翻字。1 つのリスト内で 3 通りに綴られた同じ名前は 3 つの名前として解決されます。データ上ではまさにそうなっているからです
- ハイフンのない複合名。データが支持する場合「Anna Maria」はひとまとまりに保たれますが、「Anna Maria Rossi」と「Anna Rossi」が混在するリストは一様にはなりません
この 4 つのいずれでも、国コードは問題を狭め、strict mode は不確かな行を静かにもっともらしくするのではなく見えるようにします。絞り込める空のフィールドは、気づけない誤ったフィールドより優れています
列ごとまとめて
名前がアプリケーションではなく表計算ファイルにあるなら、API は必要ありません。ファイルをアップロードし、結合された名前が入っている列を指定すれば、分割された部分がデータの隣に新しい列として返ります——CSV 1 件あたり最大 10,000,000 行、Excel ブック 1 件あたり 100,000 行までで、ブックはそのままの形で返ります
- CSV または Excel ファイルをアップロード — コード不要、元の書式はそのまま保たれます
- 一括性別判定 — 上限、大量時の価格、購買部門向けの回答
- 表計算ソフトや CRM で作業していますか？ Excel、Google Sheets、Shopify、HubSpot、Salesforce、Zapier などに 既製の連携 があります
よくある質問
スペースで分割するだけでは、なぜだめなのですか？
スペースが境界ではないからです。「Anna van der Berg」は最初のスペースで分けると姓が「van」になり、最後のスペースで分けると名が「Anna van der」になります。どちらも誤りで、どちらも英語の名前のテストでは問題なく見え、どちらもオランダ語・ドイツ語・フランス語・スペイン語・ポルトガル語の姓が来た瞬間に静かに失敗します
どこで分割するかは何が決めますか？
まず既知の敬称・肩書きが取り除かれ、「van der」「von den」「de la」などの前置詞は姓とともに残されます。その後、各部分が名として現れる頻度と姓として現れる頻度が比較されます——つまり語の位置が決めるのではなく、句読点も決めません。カンマは「姓が先」の目印として読まれるのではなく、敬称と一緒に取り除かれます。CSV と Excel のアップロードでは列の順序を明示的に指定でき、その場合は指定どおりに使われます
姓がデータベースにない場合はどうなりますか？
そのために v1 エンドポイントの strict mode があります。strict mode を有効にすると、姓は推測されるのではなく空で返るため、欠落がデータ上で見えます。無効の場合は、可能な範囲で姓が抽出されます
性別も一緒に得られますか？
はい、同じレスポンスで、同じ 1 credit で得られます——その裏付けとなるサンプル数と精度も一緒です。名前を分割して性別を判定するのは 1 回の呼び出しで、2 回ではありません
そもそも自分の列にフルネームが入っているか、どう確かめますか？
最大 100 件の値のサンプルを name-format-detect エンドポイントに送ってください。credits はかからず、その列がフルネームか、名だけか、混在かを答えます——ファイルの処理方法を決める前に役立ちます
分割はいくらかかりますか？
名前 1 件あたり 1 credit、通常の性別判定と同じで、1,000 件あたり €0.35 からです。credits は前払いで購入し、有効期限はありません
欧米以外の名前にも対応しますか？
部分的に対応します。限界を知っておくほうがよいでしょう。区切りなしで姓が先に書かれた名前、1 語だけの名前、翻字が一貫していない名前が難しいケースです——文字列だけからそれらを解決する規則は存在しません。国コードを送ると助けになります。照会が各部分をすべてに対してではなく、その国に対して比較するようになるからです
分割処理が壊れる名前で試してください
毎月 100 件の無料照会、クレジットカードは不要です。今のコードが間違える 20 行を取り出して、そこから始めてください
