名前から性別を判定するAPI｜単一リクエスト

リクエスト概要

1リクエストにつき1つの名前を送信

JSONオブジェクトで名前を送信し、Bearerトークンで認証します。地域ごとの命名傾向が推定精度の向上に役立つ場合は、国コードも追加してください。

メソッドPOST

Content-Typeapplication/json

認証Bearer Token

クレジット消費1リクエスト

HDR

必須HTTPヘッダー

リクエストを認証

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

APIキーはサーバー側の環境変数に保存してください。認証情報の安全性については、認証ガイドを確認してください。

JSONリクエストボディ

パラメータ

パラメータ	型	要否	説明
`name`	string	必須	判定する名前です。敬称や接頭辞を含まない名前を指定してください。
`country`	string	任意	地域情報を加えるISO 3166-1 alpha-2国コードです。例：JP、US。
`askToAI`	boolean	任意	trueの場合、データベースに名前がないときだけAI補完を使用します。
`forceToGenderize`	boolean	任意	trueの場合、ニックネームや一般的な人名に見えない入力も判定を試みます。

AI補完について

askToAI はデータベースに結果がない場合のみ動作します。特殊な入力を強制的に推定すると信頼性が下がる可能性があるため、probability を重要な判断材料として扱ってください。

コード例

名前の単一リクエストを送信

次の例はいずれもBearer認証を使って同じリクエストを送信します。

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

200レスポンス

性別の推定結果

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

レスポンスフィールド

フィールド	型	説明
`status`	boolean	リクエストが正常に完了したかを示します。
`used_credits`	integer	このリクエストで消費したクレジット数です。
`remaining_credits`	integer	リクエスト後に利用できるクレジット数です。
`expires`	integer	プランの有効期限をUNIXタイムスタンプで示します。
`q`	string	リクエストで送信した元の名前です。
`name`	string	GenderAPIが実際に判定した名前です。
`gender`	string \| null	推定値です。male、female、またはnullになります。
`country`	string	推定時に使用した国コードです。
`total_names`	integer	推定の根拠となった名前サンプル数です。
`probability`	integer	推定確率をパーセントで示します。
`duration`	string	サーバーでの処理時間です。

正しくエンコードした名前を送信

敬称や接頭辞を含まない名前を送信してください。JSONクライアントはエンコードを自動処理しますが、リクエストボディを作成する前に外部入力を必ず検証してください。

次のガイド

複数の名前をまとめて判定

名前の複数リクエスト1回のリクエストで複数の名前を処理 →認証APIキーの安全性を再確認 →