GenderAPI.io V2のヘルプ
よくある質問
V2のリクエスト、信頼度、不明な結果、クレジット、プライバシー、アカウントについて説明します。従来のバージョンで連携を運用している場合は、V1ドキュメントをご覧ください。
結果と信頼度
推定結果とその限界を理解する
API V2の国コンテキスト、信頼度スコア、不明な結果について説明します。
GenderAPIの結果は本人の性別を特定するものですか？
いいえ。GenderAPIは名前に関連する根拠から、またはオプションを有効にした場合はニックネームの根拠から性別を推定します。推定結果は確認済みの個人情報ではありません。不確実性を保持し、本人が表明する性自認を尊重し、重大な影響を伴う判断に推定結果だけを用いないでください。
国コンテキストは結果にどう影響しますか？
任意の大文字のISO国コードを指定すると、リクエストに地域のコンテキストが加わります。関連があり、国が分かっている場合にのみ指定してください。同じ名前でも地域によって使われ方が異なることがあります。返される国は名前との関連を示すもので、国籍や居住地を証明するものではありません。
V2の信頼度スコアは何を意味しますか？
confidenceは0～1の値で、利用できない場合はnullです。confidence_kindとあわせて読んでください。observed_frequencyはデータセット内で最も多い性別の件数を合計件数で割った値、model_reportedはAIが報告したスコアです。これらのスコアは、個人について較正された確率でも、測定された製品精度でもありません。確認のしきい値は代表的なデータを使って設定してください。
genderがnullの場合は何を意味し、課金されますか？
gender: nullを含む成功したV2の結果は、利用可能な根拠から性別を特定できなかったことを意味します。これは文字列の"null"ではなく、JSONネイティブのnullです。成功した不明な結果は、選択した料金で課金されます。不明な結果としてそのまま保持してください。プロバイダーやリクエストの失敗は、これとは別のエラーです。
さまざまな文字体系の名前を送信できますか？
はい。名前は元の文字と意味のあるアクセント記号を保ったまま、Unicodeで送信してください。対応範囲と信頼度は名前、地域、利用可能な根拠によって異なるため、アプリケーションが扱う文字体系と国を代表するサンプルでテストしてください。
APIとAI
リクエストとAIオプションを選ぶ
V2のリクエストの種類、バッチ、AIの動作、利用上限について説明します。
名前、メールアドレス、ユーザー名を1つのバッチで分析できますか？
はい。POST /api/v2/gender/batchは、APIキー使用時は最大50項目、IPトライアルでは最大10項目を受け付けます。各項目には個別のtype、value、任意のcountry、AI設定を指定できます。項目のAIはデフォルトで無効です。結果は項目ごとに確認してください。バッチは一部の項目が失敗していてもHTTP 200を返すことがあり、クレジットは不明な結果を含め、成功した項目ごとに課金されます。
メールアドレスのリクエストはどのように動作しますか？
有効なアドレスでtype: emailを使用します。APIは@より前のローカル部分から使える名前の手掛かりを探します。ドメインから本人の身元や国が分かるわけではありません。共有の受信箱や意味を読み取れないアドレスでは、不明な結果になる場合があります。単一リクエストでは、データセットで確定できない場合にデフォルトでAIフォールバックを使用します。
ユーザー名のリクエストはどのように動作しますか？
type: usernameを使用します。通常のリクエストでは、ハンドル名や表示名に含まれる認識可能な名を探します。抽象的な別名では不明な結果になることがあります。データセットで確定できなかった後にニックネームを考慮したAIを使いたい場合は、forceToGenderizeを有効にしてください。この場合、実際の名を抽出しなくても性別が推定されることがあります。
V2はいつAIを使用しますか？
単一リクエストのデフォルトはoptions.ai_mode: fallbackです。まずデータセットを確認し、性別が確定しない場合にAIを使用します。費用は合計1クレジットです。offはデータセットのみを使用して1クレジット、alwaysはデータセットを使わずにAIを使用して2クレジットです。バッチの項目はデフォルトでoffで、項目ごとにAIを有効にできます。どのモードでも、nullでない結果が得られるとは限りません。
forceToGenderizeは何をしますか？
この任意のフラグは、バッチの個々の項目を含め、名前、メールアドレス、ユーザー名の入力で使えます。データセットで確定した結果は1クレジットです。それ以外の場合はニックネームを考慮したAIが使用され、成功した不明な結果を含めて合計2クレジットです。実際の名は必要ありません。ai_modeを省略するかfallbackを使用してください。このフラグをoffまたはalwaysと組み合わせると422が返されます。
V2ではクレジットはどのように差し引かれますか？
操作の正味の課金額はmeta.usage.charged_credits、その確定状況はbilling_statusで確認できます。通常のデータセットとフォールバックによる推定は成功した項目ごとに1クレジット、alwaysとニックネームを考慮したAIは2クレジットです。完了した電話番号の検証は、無効という結果も含めて1クレジットです。開始時の残高がプラスであれば十分なため、最終的な課金で残高がマイナスになることがあります。失敗した推定は返金されます。課金が未確認の場合は、サポートによる確認が必要です。
V2にはリクエスト制限がありますか？
はい。現在のデフォルトは、アカウントごとに毎分120リクエスト、IPごとに毎分600リクエスト、アカウントごとに同時実行2件です。共有のサービス容量も影響します。POSTの本文は64 KiBまでで、バッチはキーありで50項目、IPトライアルで10項目までです。これらの上限まで常にリクエストが受け付けられるとは想定せず、HTTP 429とRetry-Afterに従ってください。
失敗またはタイムアウトしたリクエストを再試行できますか？
推定リクエストは毎回新しい操作として、通常どおり課金されます。タイムアウトやレスポンスの喪失は、課金が発生しなかったことを意味しません。再試行する前にbilling_statusを確認し、課金が未確認の場合はrequest_idを添えてサポートへお問い合わせください。一部が失敗したバッチでは、課金が確認されてから失敗した項目のみを再試行してください。429の場合はRetry-Afterに従ってください。
V2のコード例やツールはどこにありますか？
V2ガイドには、cURL、JavaScript、Python、PHP、Java、C#、Goの例があります。SwaggerとPostmanも同じV2の仕様を使用しています。入力の種類を選び、APIキーはサーバー側の設定で管理してください。
V1を引き続き使えますか？
はい。既存のV1連携は、元のエンドポイントとレスポンス形式のまま利用できます。V1とV2は同じAPIキーとクレジット残高を共有しますが、リクエストフィールド、レスポンス、エラーは異なります。既存のクライアントの保守には別途用意されたV1リファレンスを、更新の準備ができたら移行ガイドを使用してください。
プライバシーとファイル
データの取り扱いを理解する
最新の処理、保持、削除に関する情報の確認先です。
成功したGenderAPIのクエリは保存されますか？
どのクエリ記録、運用記録、セキュリティログが保持される可能性があるか、その処理目的、削除の仕組みはプライバシーポリシーで説明しています。お使いの連携について詳細を確認し、不要な個人データは送信しないでください。
メールアドレスのクエリ入力は保存されますか？
メールアドレスの入力と関連する技術記録の現在の取り扱いは、プライバシーポリシーをご覧ください。メールアドレスは個人データに該当する場合があります。リクエストに必要な情報のみを送信し、自社の診断ログに完全なアドレスを含めないでください。
アップロードしたExcel・CSVファイルはどのくらい保持されますか？
アップロードしたファイルの保持、削除、バックアップの取り扱いはプライバシーポリシーに定めています。必要な結果をエクスポートし、アップロードが不要になったらワークスペースの削除機能を使用してください。組織の保持要件に関するご質問は、サポートへお問い合わせください。
サービスプロバイダーがクエリやアップロードファイルのデータを処理することはありますか？
サービスプロバイダーによる処理と適用される保護措置は、プライバシーポリシーとサブプロセッサー情報で説明しています。データがどこで処理されるかを評価する際は、これらの資料とアカウントに適用される契約を確認してください。
アカウントとサポート
APIキーを接続してアカウントを管理する
無料利用、認証、残高の確認、サポートについて説明します。
GenderAPIを無料で試せますか？
はい。登録済みの無料アカウントには1日200クレジットが付与されます。これとは別に、キーなしで使えるV2トライアルでは、公開IPアドレスごとに24時間あたり10クレジットが付与され、V1や同じIPの他のユーザーと共有されます。どちらにも通常のクレジット料金が適用されるため、クレジット数がHTTPリクエストの回数と一致するとは限りません。
どのように認証し、APIキーを保護すればよいですか？
信頼できるサーバー側のコードからAuthorization: Bearer YOUR_API_KEYを使用してください。POSTリクエストにはContent-Type: application/jsonも必要です。実際のキーをブラウザのコード、公開リポジトリ、ログに含めないでください。キーがない場合、形式が正しくない場合、認識されない場合はIPトライアルが使用されることがあるため、meta.access.modeがapi_keyであることを確認してください。認識済みで無効化、期限切れ、または制限されたキーは、トライアルに切り替わりません。
残りのクレジットはどのように確認できますか？
BearerキーでGET /api/v2/usageを呼び出します。この残高確認は無料で、data.remaining_creditsを返します。キーを指定しない場合は、共有のIPトライアルの残高が返されます。V1とV2は同じアカウント残高を使用します。推定レスポンスのremaining_creditsは、処理完了時点のスナップショットです。
サブスクリプションの管理や解約はどこで行えますか？
GenderAPIアプリにログインし、APIキーに紐づくサブスクリプションを管理してください。現在のアカウント画面でプランと解約オプションを確認できます。
請求情報はどこで更新できますか？
対象のAPIキーまたはサブスクリプションの請求・支払い設定は、ログイン後のGenderAPIアプリで管理できます。
誤った結果の報告や連携のサポート依頼はどうすればよいですか？
APIバージョン、エンドポイント、request_id、再現可能な小さな例をサポートへ送ってください。エラーコードがあれば含めてください。ただし、APIキーや機微な個人データは削除してください。
技術情報
実装と責任ある利用のガイド
V2の結果、プライバシー、運用に関する回答です。関連ガイドへのリンクがあり、各回答にMarkdown版を用意しています。
結果、信頼度、責任ある利用
V2で性別が確定しない推定では、genderに文字列の"null"ではなくJSONネイティブのnullが使われます。名前が曖昧な場合や、利用可能な根拠が不十分な場合があります。result_statusとreasonがあれば確認してください。無理にカテゴリーに当てはめず、不明な結果として保持してください。成功した不明な推定は、選択した料金で課金されます。リクエストやプロバイダーのエラーは別の失敗であり、課金情報はmeta.usageに含まれます。
回答をすべて読む →GenderAPIの精度はどのように評価されますか？有用な精度評価では、テスト対象の集団、実施日、サンプリング方法、不明な結果の割合、地域別・文字体系別の結果を報告します。現在の評価方法のページは評価プロトコルを説明するもので、測定された精度の割合を示すものではありません。V2のconfidenceとconfidence_kindは各結果の根拠を説明しますが、代表的なデータによるベンチマークの代わりにはなりません。
回答をすべて読む →データソース、プライバシー、コンプライアンス
データの出所に関するページでは、ソースのカテゴリー、選定基準、ライセンス、地理的・文字体系上の制約を記録するための枠組みを説明しています。現在、レビュー済みのソース一覧は公開していません。そのページを確認し、連携に固有のソース要件についてはサポートへお問い合わせください。記載されていないソース、データセットの規模、対応範囲の数値を前提にしないでください。
回答をすべて読む →名前データはどのくらいの頻度で更新されますか？GenderAPIは、現在のデータの出所に関するページで、すべての名前レコードや処理ルールに共通する単一の更新スケジュールを示していません。データの鮮度が用途に影響する場合は、該当するデータセットやワークフローについてサポートに問い合わせ、代表的な結果を評価してください。ページのレビュー日は、その日にすべての基礎レコードが更新されたことを示すものではありません。
回答をすべて読む →GDPRとデータ処理契約に関する情報はどこにありますか？プライバシーポリシー、GDPR情報、データ処理契約、サブプロセッサー一覧で、公開している処理条件と保護措置を説明しています。最新の文書と、アカウントに適用される契約を確認してください。処理における役割、データの移転、データ主体からの請求など、組織固有の質問はGenderAPIへお問い合わせください。一般的なFAQは、適用される契約に代わるものではありません。
回答をすべて読む →APIの運用、エラー、課金
信頼できるサーバー側のコードからAuthorization: Bearer YOUR_API_KEYを使用してください。V2のPOSTリクエストにはContent-Type: application/jsonも必要です。GET /api/v2/genderはクエリパラメーターのキーも受け付けますが、ヘッダーを使えば認証情報がブラウザのURLに含まれません。キーがない場合、形式が正しくない場合、認識されない場合は、共有のIPトライアルが使用されることがあります。アカウントでの連携では、meta.access.modeがapi_keyであることを確認してください。認識済みで無効化、期限切れ、または制限されたキーは、トライアルに切り替わりません。
回答をすべて読む →リクエスト制限と再試行はどのように扱えばよいですか？V2はレート制限と同時実行数の制限を適用します。HTTP 429とRetry-Afterに従ってください。推定を再送信すると、毎回新しい操作として通常どおり課金されます。タイムアウト、レスポンスの喪失、課金結果が未確認の場合は、自動的に再試行しないでください。まずcode、action、meta.usage.billing_statusを確認し、billing_reconciliation_requiredの場合はrequest_idを添えてサポートへお問い合わせください。上限付きのバックオフは、課金が確認済みで、ドキュメントに記載されたactionが再試行を許可している場合にのみ使用してください。
回答をすべて読む →V2のエラーはどのように解釈しますか？V2 APIのエラーは、HTTPエラーステータスと、安定したcodeフィールドとactionフィールドを含むRFC 9457 Problem Detailsを使用します。detailの文言を照合するのではなく、これらのフィールドを読み取り、サポート用にrequest_idを保存してください。成功した不明な結果はエラーではありません。バッチのレスポンスは、HTTP 200でも項目ごとのエラーを含むことがあります。プロキシがJSON以外のエラーを返す場合もあり、レスポンスが失われたり読み取れなかったりしても、課金が発生しなかったとは限りません。
回答をすべて読む →残りのクレジットはどのように確認しますか？信頼できるサーバー側のコードから、Bearer APIキーを使ってGET /api/v2/usageを呼び出してください。このリクエストは無料で、data.remaining_creditsを返します。キーを省略すると、共有のIPトライアルの残高が読み取られます。V1とV2は同じアカウント残高を使用します。推定のmeta.usageは、その操作の課金額と完了時点の残高を示しますが、同時に実行されたリクエストによって変わることがあります。認証情報をログに残さないでください。また、残高を読み取っても、レスポンスが失われた特定のリクエストが課金されなかった証明にはなりません。
回答をすべて読む →V1からV2へ安全に移行するにはどうすればよいですか？新しい連携にはV2を使用し、既存のV1クライアントは移行を決めるまでドキュメントに記載されたパスのまま運用してください。両バージョンはAPIキーとクレジットを共有しますが、リクエストフィールド、レスポンス構造、エラー形式が異なります。移行ガイドに従い、成功、不明、エラーの各結果をテストし、エンドポイントを切り替える前にレスポンスの解析処理を更新してください。V1リファレンスは、既存の連携向けに引き続き利用できます。
回答をすべて読む →エラーを調査し、サービスの可用性を監視するにはどうすればよいですか？リクエストが失敗した場合は、返されたエラーコードを確認し、サービス障害と、無効な入力、アカウントのアクセス、クレジット不足、レート制限を区別してください。自社の連携でリクエストの成功率とレイテンシーを監視してください。原因不明の失敗や課金が不確かな場合は、request_idを添えてサポートへお問い合わせください。可用性について述べる際は、測定した監視データを根拠にしてください。このFAQは稼働率を保証するものではありません。
回答をすべて読む →解決しない場合
再現可能な例をお送りください
エンドポイント、リクエストパラメーター、返されたエラーを添えてください。ただし、本番用APIキーや機微な個人データは送信しないでください。