# ZapierをGenderAPI.io V2に接続する

> Mailchimpのレコード向けにZapierをGenderAPI.io V2に接続します。適切なコネクターを選び、typeとvalueを送信して、data、meta、クレジット、エラーを処理します。

Canonical HTML: https://www.genderapi.io/ja/blog/zapier-gender-api-integration

Last reviewed: 2026-09-29

## API契約に合ったZapierの接続方法を選ぶ

このガイドのHTTP手順では、https://api.genderapi.io/api/v2/genderでGenderAPI.io V2を呼び出します。JSONボディでtypeとvalueを送信します。推定結果はdataに、リクエストと課金の情報はmetaに含まれます。ネイティブコネクターには独自の契約があり、その内容を以下で説明します。

Zapierには、名前またはメールアドレスから性別を推定するGenderAPI.ioのアクションが掲載されています。公式掲載ページには、エンドポイントのバージョンもV2のレスポンス仕様も示されていません。後続ステップのフィールドのマッピングを変更する前に、既存のネイティブアクションの出力を確認してください。

以下のV2の設定では、Webhooks by Zapierと構造化されたPOSTのペイロードを使用します。Webhooks by Zapierを使うには、Zapierの有料プランが必要です。GenderAPIアカウントの残高と、Zapierで消費されるタスクは別々に課金されます。

- [ZapierのGenderAPI.ioアプリ公式掲載ページ](https://zapier.com/apps/gender-api/integrations)
- [既存のV1ドキュメント](https://www.genderapi.io/ja/api-documentation/v1)

## アカウントと元のレコードを準備する

この例では、メールアドレスをもとにMailchimpのレコードを拡充します。連携元と連携先のアプリへのアクセス、GenderAPI.ioアカウントのキー、HTTPアクションで使うプラットフォームの機能が必要です。このガイドには、有効な認証情報や接続済みのアカウントは含まれていません。

V1とV2は、同じアカウントのキーと同じ残高を使用します。課金対象のリクエストを設定する前に、GET /api/v2/usageでキーを確認し、このエンドポイントのレスポンスでmeta.access.modeがapi_keyになっていることを確認してください。キーがない場合や認識されない場合は、共有のIPトライアルに切り替わることがあります。本番の自動化が、気付かないうちにこれに依存する状態にしてはいけません。

設定中はワークフローを無効にしておいてください。テストで送信した推定にも通常どおりクレジットが消費されます。この手順は、公開ドキュメントとV2の仕様に照らして確認したものです。この公開にあたり、どのプラットフォームでも認証済みのワークフローを最初から最後まで実行してはいません。

- [認証と無料の使用状況確認](https://www.genderapi.io/ja/docs/v2/authentication#environment-setup)

## ZapierでGenderAPI.io V2のリクエストを設定する

- 対象の購読者レコードを提供するMailchimpのトリガーから始めます。オーディエンス（Audience）とコンタクトのIDを保存し、HTTPアクションの前に、空のメールアドレスをスキップするフィルターを追加してください。
- Webhooks by ZapierとそのPOSTアクションを選びます。以下のURLを入力し、「Payload Type」をJSONにします。データフィールドとして、type = email、options__ai_mode = offを追加し、valueにはマッピングした購読者のメールアドレスを指定します。
- Zapierでは、二重アンダースコアの表記によって、options__ai_modeがJSONボディ内のoptions.ai_modeとして入れ子になります。以下のコードブロックはAPIが受け取るボディを示したもので、アクションに追加する4つ目のフィールドではありません。
- 「Headers」に、値をBearer YOUR_API_KEYとしたAuthorizationを追加します。Content-Typeにはapplication/jsonを使用します。キーをトリガーのフィールド、クエリ文字列、サンプルのレスポンスデータに書かないでください。

| HTTP設定 | 値 | 目的 |
| --- | --- | --- |
| `Method` | `POST` | 推定のリクエストを1件送信します。 |
| `URL` | `https://api.genderapi.io/api/v2/gender` | 単一の推定に使うGenderAPI.io V2のエンドポイントです。 |
| `Authorization` | `Bearer YOUR_API_KEY` | プラットフォームの認証設定またはヘッダー設定で、このプレースホルダーを置き換えます。 |
| `Content-Type` | `application/json` | フォームのフィールドではなく、ネストされたoptionsオブジェクトを含むオブジェクトを送信します。 |
| `options.ai_mode` | `off` | 最初のテストは意図的にデータセットのみで行います。通常の課金は1クレジットで、不明な結果でも同じです。 |

## 送信前にJSONボディを確認する

この例は固定の入力を示したもので、推定結果ではありません。まずリクエストの構造を確認し、次に正しいJSONシリアライズを使ってvalueをマッピングした元のフィールドに置き換えてください。プラットフォームのマッピング式を、文字列のままAPIに送信しないでください。

ほかの入力では、typeをname、email、usernameのいずれかに設定し、対応する値をvalueに指定します。countryは、信頼できるコンテキストがある場合にのみ追加してください。このフィールドは任意であり、居住国を調べるものではありません。

**Zapier用のV2 JSONリクエスト**

```json
{
  "type": "email",
  "value": "alex@example.com",
  "options": {
    "ai_mode": "off"
  }
}
```

- [リクエストのフィールド、型、既定値](https://www.genderapi.io/ja/docs/v2/request-parameters)

## 更新を有効にする前にHTTPステップを確認する

Webhookのヘッダーは、シークレット専用のフィールドではありません。Zapを編集できる人には表示されます。アクセスを制限し、認証情報を含むZap、スクリーンショット、エクスポートを共有しないでください。Zapierには保存済みの認証情報を使うAPI by Zapierもありますが、そのリクエストボディの設定は、この構造化POSTの手順とは異なります。

ボディはラップせず、リストや配列ではなく1つのオブジェクトとして送信してください。マッピングした顧客データには、構造化JSONのアクションを選んでください。Custom Requestは生のテキストを送信し、差し込んだ値の特殊文字を自動的にエスケープしません。

- [Zapierの構造化Webhookリクエストと入れ子のJSON](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [API by Zapierの認証情報による接続](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Zapierの再実行（Replay）の動作](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)

## identifiedの結果、不明な結果、失敗を分けて処理する

送信先の更新を選ぶ前に、レスポンスボディを解析してください。以下のJSONパスはV2のボディを指します。プラットフォームによっては、ボディがラップされたりフラット化されたりすることがあります。意図的に実行する1回のテストで実際に返される構造を確認し、結果を元のレコードのIDと結び付けて保存してください。

推定は、本人の身元や本人が申告した性別を確定するものではありません。本人から提供された情報とは分けて保存してください。受け入れ基準は自社のユースケースを代表するデータに基づいて決め、データセットの信頼度とAIの信頼度は別々に評価してください。

| 確認項目 | 想定される値または型 | ワークフローでの判断 |
| --- | --- | --- |
| `meta.access.mode` | このアカウント用ワークフローではapi_key | ip_trialの場合はワークフローを止め、キーを修正してください。IPトライアルで成功したレスポンスは、アカウントが認証されたことを証明するものではなく、すでにトライアルのクレジットを消費している可能性があります。 |
| `meta.usage.billing_status` | confirmedまたはunconfirmed | unconfirmedの場合は、リクエストIDを保存し、再試行や処理の続行の前に課金を照合してください。 |
| `data.result_status / data.gender` | identifiedとmaleまたはfemale、unknownとnull | 受け入れたidentifiedの結果は、推定値専用のフィールドに保存してください。不明な結果は、既定のカテゴリーを割り当てずにそのまま保持してください。 |
| `data.confidence / data.confidence_kind` | 0から1の数値またはnull、根拠の種類またはnull | observed_frequencyとmodel_reportedは別々に解釈してください。どちらも全般的な正確性を保証するものではありません。 |
| `data.source / data.sample_count` | dataset、ai、none／整数またはnull | 推定の取得元を保存してください。AIには保存されたサンプル数がありません。データセットのサンプル数は、製品の正確性を示す指標ではありません。 |
| `meta.request_id / meta.usage` | リクエストの参照／使用状況オブジェクト | 両方をワークフローのレコードと結果とあわせて保存してください。APIキーや不要な個人データを通常のログに書き込まないでください。 |
| `HTTPの失敗／レスポンスなし` | Problem Detailsまたは完全なレスポンスなし | 更新を一時停止し、エラーと課金ステータスを確認してください。タイムアウトは、サーバーが何も処理しなかったことを証明するものではありません。 |

- [V2レスポンスの完全なリファレンス](https://www.genderapi.io/ja/docs/v2/responses)
- [エラー、タイムアウト、再試行の判断](https://www.genderapi.io/ja/docs/v2/errors-and-retries)

## Mailchimpでは対応するレコードだけを更新する

テストアクションの解析済みレスポンスを確認し、data.gender、data.result_status、および上記のほかのV2パスに対応するフィールドを選んでください。Zapierのフィールド選択では、入れ子のラベルがフラット化されることがあります。ネイティブコネクターの古いprobabilityフィールドを前提にせず、実際に確認した値と親のパスを基準にしてください。保存したIDのMailchimp購読者だけを更新します。

更新を有効にする前に、identifiedの結果、不明な結果、エラーの各分岐をテストします。架空のサンプルレスポンスを使えば、新しい推定を送信せずに分岐の条件を確認できます。連携先アプリでの更新は上記の確認に基づいて行い、関係のないフィールドやタグを上書きしないようにしてください。

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

## 再試行と重複課金を管理する

Zapを有効にする前に、ZapierのAutoreplayと手動の再実行（Replay）の設定を確認してください。失敗したWebhookアクションを再実行すると、新しいリクエストが送信されます。後続のMailchimpのステップを修正するためだけに、成功したリクエストを再実行しないでください。元の購読者のIDとリクエストの結果を一緒に保存してください。

GenderAPIへの新しいリクエストは、それぞれが独立した操作です。送信前に、保存した連携元のIDと処理ステータスを使って、ワークフロー内で繰り返された連携元イベントの重複を除いてください。連携元レコードのIDは、サーバー側で重複を防ぐキーではありません。

成功した不明な結果は、完了した課金対象の結果です。タイムアウトやレスポンスが不完全な場合は、結果も課金も分からないことがあります。リクエストの参照情報があれば保存し、リクエストを再送する前に課金を確認してください。レート制限のレスポンスにRetry-Afterヘッダーが含まれている場合は、それに従ってください。

- [クレジットと課金ステータス](https://www.genderapi.io/ja/docs/v2/credits-and-usage)

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

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

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

| リクエストのオプション | 動作 | 成功した検索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回のテストで、実際にシリアライズされたJSON、解析された結果のパス、APIキーによるアクセス、課金の確認を検証してください。可能であれば、不明な結果とエラーの処理をサンプルレスポンスでテストしてください。
- ワークフローのどのステップが再実行され、顧客のどのフィールドが変更されるかを明確にしてください。元のレコードのID、受け取ったレスポンス、リクエストの参照を保存しておけば、後で送信先で失敗しても、もう一度リクエストを送る必要はありません。
- まず小規模で管理された実行を有効にし、レコードとクレジットを確認してから並列度を上げてください。GenderAPIのクレジットと、自動化プラットフォームが課金するタスクや操作は、別々のコストです。
- バッチにはPOST /api/v2/gender/batchを使用します。APIキーによるアクセスでは最大50項目、IPトライアルでは最大10項目です。items配列には名前、メールアドレス、ユーザー名を混在させることができ、各項目に明示的なオプションと一意のidを指定します。各結果を確認してください。HTTP 200のレスポンスにも、個々の項目のエラーが含まれることがあります。ネイティブコネクターがバッチに対応しているかどうかは、別途確認が必要です。

- [バッチと項目ごとのエラー](https://www.genderapi.io/ja/docs/v2/batch)
- [Pythonでの実装ガイド](https://www.genderapi.io/ja/integrations/python)
- [Node.jsでの実装ガイド](https://www.genderapi.io/ja/integrations/javascript)

## Zapierの設定でoptions__ai_modeを使うのはなぜですか？

Webhooksの構造化POSTアクションでは、二重アンダースコアを使って入れ子のJSONを作成します。APIはoptions: {ai_mode: off}を受け取り、offは文字列です。トップレベルのoptions__ai_modeという名前のフィールドをそのまま受け取るわけではありません。

## HTTPを直接使う例ではAIが使われますか？

最初のリクエストのボディでは、options.ai_modeをoffに設定しています。通常のAIフォールバックを使う場合は、意図的に値をfallbackに変更してください（合計1クレジット）。直接AIを使う場合はalwaysに変更します（2クレジット）。forceToGenderizeは最初にデータセットを参照します。データセットで解決した場合は1クレジット、AIが使われた場合は合計2クレジットです。

## 不明な結果は無料で、自動的に再送しても安全ですか？

いいえ。成功した不明な結果は完全な結果であり、課金されます。再試行は新しい検索です。通信エラーや課金が未確認の場合は、返された使用状況のデータとリクエストの参照を確認してから、再送するかどうかを判断してください。

## このワークフローは、接続したアカウントで実行されましたか？

いいえ。各プラットフォームの設定手順は、2026年9月26日に公開ドキュメントに基づいて確認しました。GenderAPI.io V2のリクエストとレスポンスの説明は、2026年9月27日に確認しました。この日本語版の2026年9月29日のレビューは翻訳の確認であり、アカウントを使った新しいテストではありません。本番の更新を有効にする前に、選択したアクションの現在のフィールド、認証、リクエストボディ、レスポンス、再試行の動作をご自身のアカウントで確認してください。

## 出典とドキュメント

- [ZapierのGenderAPI.ioアプリ公式掲載ページ](https://zapier.com/apps/gender-api/integrations)
- [Zapierの構造化Webhookリクエストと入れ子のJSON](https://help.zapier.com/hc/en-us/articles/8496326446989-Send-webhooks-in-Zap-workflows)
- [API by Zapierの認証情報による接続](https://help.zapier.com/hc/en-us/articles/44391660158733-How-to-get-started-with-API-by-Zapier)
- [Zapierの再実行（Replay）の動作](https://help.zapier.com/hc/en-us/articles/19220226086797-What-is-replay)
- [GenderAPI.io V2のリクエスト仕様](https://www.genderapi.io/ja/docs/v2/request-parameters)
- [GenderAPI.io V2のレスポンス仕様](https://www.genderapi.io/ja/docs/v2/responses)
- [GenderAPI.io V2の課金とクレジット](https://www.genderapi.io/ja/docs/v2/credits-and-usage)