PythonでGenderAPI.io V2を使う

サーバー側のPythonプロジェクトを準備する

このガイドでは、BearerのAPIキーを使ってGenderAPI.io V2のエンドポイントhttps://api.genderapi.io/api/v2/genderを呼び出します。Python 3.10以降を使い、genderapi_v2.pyをプロジェクトにダウンロードしてください。例ではPythonの標準ライブラリのurllib.requestとjsonを使うため、pipのパッケージは必要ありません。

サーバーの環境にGENDERAPI_API_KEYを設定してください。以下の例のYOUR_API_KEYは有効なキーではありません。本物の認証情報を、コミットするファイル、共有するノートブック、クライアント側のアプリケーションに含めないでください。モジュールをインポートしたり、デモのオプションを付けずに実行したりしても、リクエストは送信されません。

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi_v2.pyをダウンロード →
• 無料の使用状況エンドポイントでキーを確認する →

データセットのみを明示したリクエストを1回送信する

次のコードをダウンロードしたファイルと同じ場所にsingle.pyとして保存し、python3 single.pyを実行します。ヘルパーは、type: name、value: Alice、options.ai_mode: offをJSONで送信します。推定結果はdataで、リクエストと課金の詳細はmetaで確認してください。

成功した呼び出しは、不明な結果を含めて1クレジットを消費します。サンプルの名前で推定結果が得られるとは限りません。make_itemはname、email、usernameを受け付け、明示的なAIモードを必要とします。countryは、関連するコンテキストがある場合にのみ追加してください。

ヘルパーは、何かを送信する前に24文字の16進数のAPIキーを求めます。確認するのはキーの形式であり、キーが存在するかどうかではありません。また、IPトライアルの成功レスポンスを想定外のアクセスモードとして拒否します。この確認はレスポンスを受け取った後に行われるため、すでに使われたIPトライアルのクレジットは戻りません。

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• 単一リクエストのすべてのフィールド →

結果とその根拠をあわせて保存する

推定された関連付けは、本人が申告した性別ではありません。元の入力、返された根拠、本人から提供された情報は分けて保存してください。不明な結果は有効な結果であり、アプリケーション内で推測によるカテゴリーに置き換えるべきではありません。

• レスポンスフィールドと不明な結果 →
• 精度と信頼度の説明 →
• データソースと日付付きのデータベース概要 →

混在したバッチを処理し、行のidを保持する

GenderAPI.io V2では、混在したバッチをPOST https://api.genderapi.io/api/v2/gender/batchで処理します。アカウントのキーでは最大50項目、IPトライアルでは最大10項目です。これらの例にはアカウントのキーが必要です。すべての項目に、安定した一意のidと明示的なAIモードを指定してください。1つのバッチに名前、メールアドレス、ユーザー名を混在させることができ、各項目に任意で国のコンテキストを指定できます。

dataに含まれるすべての項目と、meta.summaryの集計を確認してください。HTTP 200でも項目のエラーが含まれることがあります。すべての項目が失敗したバッチは、結果を含むトップレベルのProblemレスポンスになることがあります。成功した不明な結果はsucceededとして数えられます。元のindexとidを使うと、各結果を正しい元の行に対応付けられます。

大きなジョブでは、入力を最大50項目ずつのグループに分け、最初は順番に送信してください。次に進む前に、各レスポンスとその使用状況を保存します。通信、アカウント、未確定の課金に関する失敗が起きたら処理を止め、現在のグループの状況を確認してください。並列処理は、アカウントの上限を確認してから追加してください。バッチの最大項目数は、処理能力を保証するものではありません。

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• バッチの入力、結果、課金 →

AIを使うタイミングを選ぶ

forceToGenderizeは、名前、メールアドレス、ユーザー名のいずれでも任意で使用できます。有効にする場合は、ai_modeを省略するかfallbackを使用してください。offとalwaysは併用できず、422が返ります。最終的な課金で残高がマイナスになる場合でも、開始時の残高がプラスであればリクエストを開始できます。

ニックネームモードでは、name: nullのまま性別が返ることがあります。不明な結果になることもあります。通常のフォールバックもニックネームの推定も、正しい回答やnullでない回答を保証するものではありません。

このPythonのヘルパーでは、ai_modeが常に必要です。ニックネームの推定を許可するには、次のように呼び出してください：make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True)。ヘルパーはforce_to_genderizeをJSONのフィールドforceToGenderizeに変換します。

• AIオプションとニックネームの推定 →
• クレジットと使用状況 →

失敗した後の対応を決める

例では、各操作を1回だけ送信します。自動的に再試行することはありません。再送は新しい操作であり、課金の対象になります。タイムアウトや接続の失敗は、クライアントが完全なレスポンスを受け取れなかったことを意味します。サーバーが処理を止めたことや、クレジットが消費されなかったことを証明するものではありません。

返されたリクエストIDと課金の状態を、ジョブの記録とあわせて保存してください。エラーオブジェクトは、管理された形で確認できるようにレスポンスを保持しますが、元の入力が含まれていることがあります。オブジェクト全体、レスポンス、APIキーを通常のログに書き込まないでください。

• Problem Detailsと再試行の判断 →
• クレジットと課金の確認 →

この例の通信の動作を理解する

urllibの10秒のタイムアウトは、ブロッキングするソケット操作に適用されるもので、リクエスト全体の所要時間の上限を保証するものではありません。この例はHTTPのリダイレクトを無効にし、成功したJSONを解析し、HTTPのProblemレスポンスを保持します。自動的に再試行することはありません。

ローカルのテストでは、成功、不明な結果、部分的に失敗したバッチ、アカウントのアクセス、失敗について、合成した通信のフィクスチャーを使います。これらは例の処理の流れを確認するもので、本番のAPIの可用性、推定の精度、レスポンス時間を測定するものではありません。下にある明示的なデモのコマンドは、それぞれ独自のリクエストを送信し、課金されます。

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Pythonのリファレンス：urllib.request →
• Pythonのリファレンス：HTTPError →

よくある質問