# JavaScriptとNode.jsでGenderAPI.io V2を使う

> 組み込みのfetchで、Node.jsからGenderAPI.io V2を呼び出します。単一リクエストと混在したバッチ、dataとmetaのレスポンス、クレジットを考慮したエラー処理のためのESモジュールをダウンロードできます。

Canonical HTML: https://www.genderapi.io/ja/integrations/javascript

Last reviewed: 2026-10-01

## 実行環境とダウンロードできる例

Node.js 22+。ダウンロードできるHTTP連携の例です。別途公開されているSDKではありません。GenderAPI.ioの公式SDKも利用できます。

- [例をダウンロード](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [GenderAPI.ioの公式SDK](https://www.genderapi.io/ja/docs/v2/sdks)

## 連携はNode.jsのサーバー上に置く

このガイドでは、BearerのAPIキーを使ってGenderAPI.io V2のエンドポイントhttps://api.genderapi.io/api/v2/genderを呼び出します。Node.js 22以降を使い、genderapi-v2.mjsをプロジェクトにダウンロードしてください。このESモジュールは組み込みのfetchとAbortSignal.timeoutを使うため、npmのパッケージは必要ありません。拡張子が.mjsなので、package.jsonを変更せずに別のESモジュールからインポートできます。

サーバーの環境にGENDERAPI_API_KEYを設定してください。キーをReact、Vue、その他のブラウザーで動くJavaScriptに含めないでください。アプリケーションのユーザーの認証は自分のサーバーで行い、GenderAPI.ioの呼び出しもサーバーから行ってください。以下の例のYOUR_API_KEYは有効なキーではありません。モジュールをインポートしたり、明示的な実行オプションを付けずに実行したりしても、リクエストは送信されません。

**Node.js環境を設定する**

```bash
node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [genderapi-v2.mjsをダウンロード](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [無料の使用状況エンドポイントでキーを確認する](https://www.genderapi.io/ja/docs/v2/authentication#environment-setup)

## 明示的なAIの方針を付けてJSONのPOSTを1回送信する

このコードをダウンロードしたモジュールと同じ場所にsingle.mjsとして保存し、node single.mjsを実行します。V2のフィールドtypeとvalueを、options.ai_mode: offとともに送信します。推定結果はresponse.dataで、リクエストと課金の詳細はresponse.metaで確認してください。

完了した検索は、genderがnullでも1クレジットを消費します。サンプルの名前で特定の結果が得られるとは限りません。

ヘルパーは、明示的なAIモードと24文字の16進数のキーを求め、meta.access.modeがapi_keyであることを確認します。IPトライアルの成功レスポンスは、黙って処理を続けるのではなく、想定外のアクセスモードのエラーになります。ヘルパーがこの不一致を検出する前に、サーバーがIPトライアルのクレジットをすでに1回分消費していることがあります。

**Node.jsでの単一の検索**

```javascript
import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}
```

- [単一リクエストのすべてのフィールド](https://www.genderapi.io/ja/docs/v2/request-parameters)

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

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

| フィールド | 使い方 |
| --- | --- |
| `data.gender / data.result_status` | maleまたはfemaleは、identifiedの場合にのみ使用します。結果が不明な場合は、JSONのnullをそのまま保持します。 |
| `data.name / data.match` | 返された名前と選ばれた候補を確認します。部分文字列での一致は、その入力がその名を持つ人のものであることを証明しません。 |
| `data.confidence / data.confidence_kind` | 信頼度は0–1の値またはnullです。observed_frequencyは保存された件数に基づき、model_reportedはAIのスコアです。しきい値は種類ごとに別々に評価してください。 |
| `data.source / data.sample_count` | dataset、ai、noneを区別します。AIの結果には保存されたサンプル数がありません。サンプル数は測定された精度ではありません。 |
| `meta.access.mode` | アカウントとの連携では、api_keyであることを確認します。キーがない場合や認識されない場合は、代わりに共有のIPトライアルが使われることがあります。 |
| `meta.usage` | charged_creditsとbilling_statusを確認します。成功した不明な結果も課金されます。レスポンスを受け取れなかったことは、そのリクエストが無料だったことを意味しません。 |

- [レスポンスフィールドと不明な結果](https://www.genderapi.io/ja/docs/v2/responses)
- [精度と信頼度の説明](https://www.genderapi.io/ja/accuracy-methodology)
- [データソースと日付付きのデータベース概要](https://www.genderapi.io/ja/data-provenance)

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

**Node.jsでのバッチ検索**

```javascript
import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}
```

- [バッチの入力、結果、課金](https://www.genderapi.io/ja/docs/v2/batch)

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

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

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

このJavaScriptのヘルパーでは、options.ai_modeが常に必要です。ニックネームの推定には、forceToGenderize: trueとoptions: { ai_mode: 'fallback' }をあわせて送信してください。

| リクエストのオプション | 動作 | 成功した検索1件あたりのクレジット |
| --- | --- | --- |
| options.ai_mode: off | データセットのみを使用します。 | 1（不明な結果を含む） |
| options.ai_mode: fallback | まずデータセットを確認し、性別が返らない場合に通常のAIを使用します。単一リクエストのデフォルトです。 | 合計1（AIフォールバックを含む） |
| options.ai_mode: always | 直接AIに問い合わせます。 | 2 |
| forceToGenderize: true | まずデータセットを確認し、その後、実名がなくても個人のニックネームやエイリアスをAIが解釈できるようにします。 | データセットで推定できた場合は1、AIを使った場合は合計2 |

- [AIオプションとニックネームの推定](https://www.genderapi.io/ja/docs/v2/ai-options)
- [クレジットと使用状況](https://www.genderapi.io/ja/docs/v2/credits-and-usage)

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

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

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

| 結果 | アプリケーションでの判断 |
| --- | --- |
| 成功した不明な結果 | null、reason、usageを保持します。これは完了した課金対象の結果であり、自動的に再試行する失敗した行ではありません。 |
| 422の検証エラー | 新しいリクエストを送る前に、Problem Detailsのフィールドで示された入力を修正します。 |
| 401 / 403 | アカウントのアクセス権や利用できるクレジットを確認します。同じリクエストを繰り返し送信しても、根本的な問題は解決しません。 |
| 429 | Retry-Afterがある場合はそれに従います。エラーと課金の状態を確認し、次の試行を意図的に後で予定します。 |
| ネットワークエラー、タイムアウト、読み取れないレスポンス | 結果と課金が確認できていないことを記録します。再送する前に状況を照合してください。サーバーで完了した処理をクライアントから取り消すことはできません。 |
| billing_status: unconfirmed | charged_creditsとremaining_creditsがnullになることがあります。再試行する前に、request_idを添えてサポートに連絡してください。nullをゼロに置き換えないでください。 |
| バッチの一部の項目が失敗 | まず完了した項目を保存します。失敗した項目とその課金を確認し、バッチ全体ではなく、再送が適切な失敗項目だけを送り直します。 |

- [Problem Detailsと再試行の判断](https://www.genderapi.io/ja/docs/v2/errors-and-retries)
- [クレジットと課金の確認](https://www.genderapi.io/ja/docs/v2/credits-and-usage)

## fetchのタイムアウトとレスポンスの確認を理解する

デフォルトのタイムアウトは、AbortSignal.timeoutを使った10,000ミリ秒で、レスポンスの本文の読み取りも含まれます。クライアントが中断しても、サーバーでの処理や課金が止まったことにはなりません。このモジュールはリダイレクトを無効にし、HTTPの失敗と読み取れないレスポンスを区別し、自動的に再試行することはありません。

通信のフィクスチャーを使ったテストでは、成功したレスポンス、不明な結果、部分的に失敗したバッチ、認証情報のフォールバック、エラーを確認します。これらのテストには実際の推定やクレジットの操作は必要なく、本番の可用性や精度のベンチマークでもありません。下にある明示的なデモのコマンドは、それぞれ独自のリクエストを送信し、課金されます。

**任意で明示的に実行するNode.jsのデモ**

```bash
node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch
```

- [Node.jsのリファレンス：fetch](https://nodejs.org/api/globals.html#fetch)
- [Node.jsのリファレンス：AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## このコードをブラウザーのJavaScriptに貼り付けて使えますか？

コードはサーバー上に置いてください。ブラウザー向けのバンドルでは、APIキーがユーザーに見えてしまいます。ブラウザーからは認証済みの自社のバックエンドを呼び出し、そのバックエンドからGenderAPI.ioにリクエストを送信してください。

## 不明な結果でもクレジットを消費しますか？

はい。成功した通常の検索は、genderがnullでも1クレジットを消費します。通常のAIフォールバックはこのクレジットに含まれます。alwaysのAIは2クレジットです。forceToGenderizeは、データセットで推定できた場合は1クレジット、AIを使った場合は2クレジットです。

## この例は失敗したリクエストを再試行しますか？

いいえ。新しいリクエストはそれぞれ独立した操作です。再送するかどうかを決める前に、エラー、項目ごとの結果、課金の状態を確認してください。レスポンスがなかったことは、前回の試行が無料だったことを意味しません。

## パッケージをインストールする必要がありますか？

いいえ。このGenderAPI.ioのガイドから例を直接ダウンロードしてください。実行時にサードパーティーの依存関係はなく、別途公開されているSDKでもありません。メンテナンスされているパッケージを使いたい場合は、GenderAPI.ioの公式SDKが同じV2 APIを呼び出します。Pythonではpip install genderapi、JavaScriptではnpm install genderapiを使用します。例のコードを確認し、アプリケーションに合わせて調整してください。APIの仕様は、GenderAPI.io V2のドキュメントに従います。

## リファレンス

- [GenderAPI.io V2の認証](https://www.genderapi.io/ja/docs/v2/authentication)
- [V2のレスポンスフィールド](https://www.genderapi.io/ja/docs/v2/responses)
- [バッチの結果と上限](https://www.genderapi.io/ja/docs/v2/batch)
- [エラーと再試行のリファレンス](https://www.genderapi.io/ja/docs/v2/errors-and-retries)
- [GenderAPI.ioの公式SDK](https://www.genderapi.io/ja/docs/v2/sdks)