1つの文字体系や命名パターンを前提にせず、元の名前を使う このデモでは、デーヴァナーガリーの例とINの国のコンテキストを使っています。これは入力の一例であり、インドで使われるすべての名前を定義するものではありません。APIはUnicodeの文字列を受け取るため、レコードにある綴りを、先にラテン文字に変換せずにそのまま送信できます。
データセットの照合では正規化されたトークンを使い、文字体系の一般的な変換は行いません。ラテン文字の綴りと元の文字体系の綴りが同じレコードに結び付くことも約束していません。返された名前とあわせて元の入力を保持してください。ある文字体系を受け付けることは、その言語やコミュニティについて精度が独立して測定されていることを意味しません。
最初や最後のトークンの役割が決まっていると考えないでください。V2は、特定の位置の名を保証するのではなく、保存されている合計件数が最も多い利用可能な候補レコードを選びます。イニシャル、短いトークン、保存済みの一致がないことによって、データセットの結果が決まらないことがあります。AIフォールバックでは、送信された値全体が試されることがあります。
INの国のコンテキストを意図して選ぶ ライブデモはcountry: IN(インド)を送信します。APIが名前の文字体系からこの国を選ぶわけではありません。連携では、分かっている関連するコンテキストを使うか、countryを省略してください。このサンプル値をすべてのレコードのデフォルトにしないでください。
候補ごとに、データセットの照合では国別のレコードがあればそれを優先し、なければグローバルのレコードを検討します。そのうえで、保存されている合計件数が最も多い利用可能な候補が選ばれます。実際の照合範囲はdata.match.scopeとdata.match.countryで確認してください。件数が同数で判断できない国別のレコードが、自動的にグローバルの結果に置き換えられることはありません。代わりにフォールバックでAIが使われることがあります。
data.input.countryはリクエストのコンテキストを示します。data.countryとdata.country_sourceは、返された関連付けを示します。これらは別々のフィールドであり、国籍、民族、居住地を証明するものではありません。
インドで使われる名前をV2で送信する 既存のAPIキーをGENDERAPI_API_KEYに設定し、サーバー上でリクエストを実行してください。この例では通常のAIフォールバックを明示的に有効にしています。これはリクエストの例であり、測定された推定結果やカバレッジの結果を示すものではありません。データセットのみで処理するには、options.ai_mode: offを使用してください。
プログラミング言語を選んでください。 APIキーを設定する 。次に、サーバー上で例を実行してください。
推定のリクエストは、再試行を含め、毎回新たに課金される処理です。これらの例は自動的に再試行しません。次のリクエストを送信する前に課金ステータスを確認してください。
実行する前に:アクセスとエラー処理 これらの例はサーバー上で実行してください。プロセスの環境変数GENDERAPI_API_KEY に既存のAPI キーを設定し、meta.access.mode がapi_key であることを確認します。認識されないキーはIPトライアルに切り替わることがあります。
HTTP 4xxと5xxのJSON レスポンスでは、例はエラーのボディをそのまま残し、0以外の終了ステータスで終了します。再試行する前にcode 、action 、meta.usage.billing_status を確認してください。
エラーと再試行のガイド → cURL JavaScript Python PHP Java C# / .NET Go
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": "प्रिया शर्मा",
"country": "IN",
"options": {
"ai_mode": "fallback"
}
}' 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" : "प्रिया शर्मा" ,
"country" : "IN" ,
"options" : {
"ai_mode" : "fallback"
}
};
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 \" : \" प्रिया शर्मा \" , \" country \" : \" IN \" , \" options \" :{ \" ai_mode \" : \" fallback \" }}" )
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":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}' , 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 \" : \" प्रिया शर्मा \" , \" country \" : \" IN \" , \" options \" :{ \" ai_mode \" : \" fallback \" }}" ;
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 \" : \" प्रिया शर्मा \" , \" country \" : \" IN \" , \" options \" :{ \" ai_mode \" : \" fallback \" }}" , 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 \" : \" प्रिया शर्मा \" , \" country \" : \" IN \" , \" options \" :{ \" ai_mode \" : \" fallback \" }}"
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を実行します。実行環境のドキュメント
結果とその根拠をあわせて保存する 推定された関連付けは、本人が申告した性別ではありません。元の入力、返された根拠、本人から提供された情報は分けて保存してください。不明な結果は有効な結果であり、アプリケーション内で推測によるカテゴリーに置き換えるべきではありません。
AIを使うタイミングを選ぶ forceToGenderizeは、名前、メールアドレス、ユーザー名のいずれでも任意で使用できます。有効にする場合は、ai_modeを省略するかfallbackを使用してください。offとalwaysは併用できず、422が返ります。最終的な課金で残高がマイナスになる場合でも、開始時の残高がプラスであればリクエストを開始できます。
ニックネームモードでは、name: nullのまま性別が返ることがあります。不明な結果になることもあります。通常のフォールバックもニックネームの推定も、正しい回答やnullでない回答を保証するものではありません。
名前のリストを、コンテキストを失わずに処理する POST /api/v2/gender/batchを使うと、登録済みのAPIキーでは最大50項目、IPトライアルでは最大10項目を送信できます。各項目に一意のidを付け、行ごとに元の値を保持してください。項目ごとに国とAIの設定を指定できます。国が分からない場合は省略してください。
単一リクエストのデフォルトがフォールバックであるのとは異なり、バッチの項目はデフォルトでデータセットのみを使用します。AIが必要な項目には、それぞれoptions.ai_mode: fallbackを設定してください。HTTP 200が返った場合でもすべての結果を確認し、不明な結果を保持し、再送する前に項目のエラーと課金を確認してください。成功した通常の項目はそれぞれ1クレジットを消費します。1回のバッチのHTTPリクエストが、1回分の推定のクレジットになるわけではありません。
よくある質問 インドで使われる名前のデモは、ヒンディー語の名前だけに対応していますか? デモではデーヴァナーガリーの例を1つ使っていますが、APIはUnicodeの名前の文字列を受け付けます。この入力機能は、データセットのカバレッジが完全であることや、インドで使われるすべての言語について精度が測定されていることを示すものではありません。
ラテン文字の綴りでも、元の文字体系と同じ結果になりますか? 保証はありません。現在のデータセットの照合では、翻字の一般的な同一視は行われません。送信した綴りごとに、返されたsource、match、信頼度の情報をまとめて保持してください。
インドで使われる名前について、精度は測定されていますか? そのような測定結果は、このページでは公開していません。入力が受け付けられること、保存された件数、信頼度の値は、独立した精度のベンチマークではありません。利用できる根拠と、まだ公開されていない測定については、評価方法のページを確認してください。
不明な結果でもクレジットを消費しますか? 成功した不明な結果は課金対象です。通常のデータセットモードまたはフォールバックモードでは、合計1クレジットです。forceToGenderizeを有効にした場合、データセットで推定できた結果は1クレジット、AIを使うと不明なAIの結果を含めて合計2クレジットです。エラーには別の課金ルールが適用されます。meta.usageを確認してください。