API V2で名前から性別を推定

リクエストを送信する前に

JSONをPOST https://api.genderapi.io/api/v2/gender に送信します。既存のAPIキーをAuthorization: Bearer YOUR_API_KEYで指定し、Content-Type: application/jsonを付けてください。各リクエストは個別に処理されます。

コード例でプログラミング言語を選んでください。実行前にプロセスの環境変数GENDERAPI_API_KEYを設定します。キーがない場合や認識されない場合は共有のIPトライアルが使われることがあるため、アカウントを連携するときはmeta.access.modeがapi_keyであることを確認してください。

名前から性別を推定

パラメーター	型	必須	デフォルト	説明
`type`	`string`	はい	`—`	入力の種類：name、email、username。
`value`	`string`	はい	`—`	必須。1–254文字。空白のみは不可で、制御文字は使用できません。emailの値はメールアドレスとして有効な構文である必要があります。
`country`	`string`	いいえ	`—`	任意。大文字のISO 3166-1 alpha-2コード（例：TR、US）。国別の検索はグローバルデータセットにフォールバックすることがあります。
`forceToGenderize`	`boolean`	いいえ	`false`	まずデータセットを確認し、推定できない場合はニックネームを解釈するAIを使用します。name、email、usernameで使用できます。
`options`	`object`	いいえ	`—`	入力ごとのAIオプションを格納するオブジェクト。
`options.ai_mode`	`string`	いいえ	`fallback`	使用できる値：off、fallback、always。forceToGenderize: trueの場合は、このフィールドを省略するかfallbackを使用してください。
`id`	`string`	いいえ	`—`	POSTのJSONで指定できる1–64文字の任意の識別子。バッチの各結果とともに返され、バッチ内で一意である必要があります。単一の推定でも受け付けますが、レスポンスには含まれません。GETクエリでは使用できません。

名またはフルネームにはtype: nameを使用します。成功したレスポンスでもgender: nullが含まれることがあります。単一リクエストではまずデータセットを確認し、性別を推定できない場合はデフォルトでAIを使用します。

プログラミング言語を選んでください。APIキーを設定する。次に、サーバー上で例を実行してください。

推定のリクエストは、再試行を含め、毎回新たに課金される処理です。これらの例は自動的に再試行しません。次のリクエストを送信する前に課金ステータスを確認してください。

実行する前に：アクセスとエラー処理

これらの例はサーバー上で実行してください。プロセスの環境変数GENDERAPI_API_KEYに既存のAPIキーを設定し、meta.access.modeがapi_keyであることを確認します。認識されないキーはIPトライアルに切り替わることがあります。

HTTP 4xxと5xxのJSONレスポンスでは、例はエラーのボディをそのまま残し、0以外の終了ステータスで終了します。再試行する前にcode、action、meta.usage.billing_statusを確認してください。

エラーと再試行のガイド →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "Hiroshi",
  "country": "JP"
}'

POSIXシェルでcURL 7.76以上。ターミナルで実行します。実行環境のドキュメント

// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "Hiroshi",
  "country": "JP"
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22以上、組み込みのfetch。example.mjsとして保存し、node example.mjsを実行します。実行環境のドキュメント

import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"Hiroshi\",\"country\":\"JP\"}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10以上、標準ライブラリ。example.pyとして保存し、python3 example.pyを実行します。実行環境のドキュメント

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Hiroshi","country":"JP"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8以上とcURL拡張機能。example.phpとして保存し、php example.phpを実行します。実行環境のドキュメント

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"Hiroshi\",\"country\":\"JP\"}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17以上、標準のHTTPクライアント。GenderApiExample.javaとして保存し、java GenderApiExample.javaを実行します。実行環境のドキュメント

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"Hiroshi\",\"country\":\"JP\"}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

.NET 8以上のコンソールアプリケーション。コンソールプロジェクトのProgram.csとして使用し、dotnet runを実行します。実行環境のドキュメント

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"Hiroshi\",\"country\":\"JP\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22以上、標準ライブラリ。main.goとして保存し、go run main.goを実行します。実行環境のドキュメント

レスポンスの例

これは2026年10月1日にAPIキーで取得した実際のレスポンスで、アカウント残高のみを置き換えています。精度を測るものではなく、実際のリクエストでは異なる結果が返ることがあります。APIキーによるリクエストではmeta.access.mode: api_keyが返り、IPトライアル専用の上限フィールドはnullになります。IPトライアルによるリクエストではip_trialが返ります。推定結果はdataで、その処理の課金結果はmeta.usageで確認してください。

{
  "data": {
    "input": {
      "type": "name",
      "value": "Hiroshi",
      "country": "JP"
    },
    "name": "hiroshi",
    "gender": "male",
    "country": "JP",
    "confidence": 0.9961046188091264,
    "confidence_kind": "observed_frequency",
    "sample_count": 1797,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "hiroshi",
      "method": "normalized",
      "scope": "country",
      "country": "JP"
    }
  },
  "meta": {
    "request_id": "a7b93719-5d6e-4150-8d5d-3b494120ffe2",
    "duration_ms": 12,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

レスポンスフィールドと信頼度

推定のレスポンスフィールド

フィールド	型	nullの場合あり	例	説明
`data.input`	`object`	いいえ	`{"type":"name","value":"Hiroshi","country":"JP"}`	入力の種類、値、国。trueの場合はforceToGenderizeも含まれます。
`data.name`	`string`	はい	`"hiroshi"`	一致した名、または抽出された名。該当がない場合はnull。
`data.gender`	`string`	はい	`"male"`	male、female、またはJSONのnull。推定であり、確認された個人の属性ではありません。
`data.result_status`	`string`	いいえ	`"identified"`	性別が返された場合はidentified、それ以外はunknown。
`data.reason`	`string`	はい	`null`	identifiedの場合はnull。不明の理由：not_found、no_name_candidate、ambiguous、insufficient_evidence。
`data.confidence`	`number`	はい	`0.95`	0–1のスコア、またはnull。性別がnullの場合、信頼度もnullです。
`data.confidence_kind`	`string`	はい	`"observed_frequency"`	observed_frequency：データセットで多数を占める性別の件数÷合計件数。model_reported：AIが報告したスコアで、較正済みの確率ではありません。取得できない場合はnull。
`data.sample_count`	`integer`	はい	`1200`	データセットのサンプル数、またはnull。AIがサンプル数を作り出すことはありません。
`data.source`	`string`	いいえ	`"dataset"`	dataset、ai、noneのいずれか。
`data.country`	`string`	はい	`"JP"`	datasetまたはai_associationによる国との関連付け、またはnull。国籍、居住地、民族を示すものではありません。
`data.country_source`	`string`	はい	`"dataset"`	国との関連付けの出どころ：dataset、ai_association、またはnull。
`data.match`	`object`	いいえ	`{"name":"hiroshi","method":"normalized","scope":"country","country":"JP"}`	一致したデータセットの名前、照合方法（normalized、token、substring、model_inference）、country/globalの範囲、一致した国。取得できない根拠はnullになります。

アクセス、課金、リクエストのメタデータ

フィールド	型	nullの場合あり	例	説明
`meta.request_id`	`string`	いいえ	`"550e8400-e29b-41d4-a716-446655440000"`	このHTTPの試行を一意に識別するID。X-Request-IDでも返されます。
`meta.duration_ms`	`integer`	いいえ	`42`	リクエストの処理時間（ミリ秒）。
`meta.access.mode`	`string`	いいえ	`"api_key"`	api_key、ip_trial、unauthenticatedのいずれか。有料アカウントを使う場合はapi_keyであることを確認してください。
`meta.access.reason`	`string`	はい	`null`	IPトライアルに切り替わった理由：api_key_missing、api_key_invalid、api_key_not_found。それ以外はnull。
`meta.usage.charged_credits`	`integer`	はい	`1`	差し引かれた正味のクレジット。課金前、または全額の払い戻しが確認された後は0。課金が未確定の場合はnull。
`meta.usage.remaining_credits`	`integer`	はい	`99`	処理完了時の残高。マイナスになることがあります。取得できない場合や課金が未確定の場合はnull。
`meta.usage.billing_status`	`string`	いいえ	`"confirmed"`	not_charged、confirmed、unconfirmedのいずれか。失敗した推定を再試行する前に確認してください。
`meta.usage.resets_at`	`string`	はい	`"2026-09-27T12:00:00.000Z"`	IPトライアルのリセット時刻（UTC、ISO 8601）。APIキーのアカウントや不明な場合はnull。
`meta.usage.limit`	`integer`	はい	`10`	IPトライアルのクレジット上限。APIキーのアカウントではnull。
`meta.usage.period_seconds`	`integer`	はい	`86400`	IPトライアルの期間（秒）。APIキーのアカウントではnull。

国のコンテキストと不明な名前

countryは関連するコンテキストがある場合にのみ指定してください。APIは国別のデータセット行を選ぶことも、グローバル行にフォールバックすることもあります。どちらが選ばれたかはdata.match.scopeで確認できます。返された国は、その人の居住地を示すものではありません。

単一リクエストはデフォルトでAIフォールバックを使用し、合計1クレジットを消費します。データセットのみを使う場合はoptions: {"ai_mode": "off"}を送信してください。推定できなかった入力はgender: nullを返すことがあり、処理が成功していれば課金されます。フルネームは構成要素の一部で一致することがあり、選ばれた候補と照合方法はdata.matchに記録されます。

ニックネームのような名前の値では、forceToGenderize: trueを指定すると実名がなくても推定できます。データセットで推定できた場合は1クレジット、そうでない場合はニックネームを解釈するAIを使い、合計2クレジットです。開始時の残高がプラスであれば十分で、処理後の残高はマイナスになることがあります。

フルネームを調べるときは、最初の語が選ばれると決めつけない

元のUnicodeの名前をそのまま送信してください。データセットの照合では、NFKC正規化、小文字化、構成要素の抽出が行われるため、名前をASCIIに変換する必要はありません。APIは、利用できる候補レコードのうち、保存されている合計件数が最も多いレコードを選びます。その候補は名前の後ろの部分であることもあるため、最初の語や名が選ばれたと決めつけないでください。

このリクエストはデータセットのみを使うため、選ばれた根拠を確認しやすくなります。送信したフルネームはdata.input.value、検索に使われた候補はdata.match.name、照合方法はdata.match.methodで確認してください。この例は、特定の性別や特定の構成要素が選ばれることを約束するものではありません。データセットの候補は3文字以上である必要があり、短い入力は推定できないことがあります。追加の推定がアプリケーションにとって適切な場合は、通常のAIフォールバックを使用してください。