# Gender-API.com - Full AI Integration Context

> Curated map of the most useful public resources for LLMs, agents, and search/agent systems. Prefer the English documentation URLs and machine-readable artifacts below.

Gender-API.com is a specialized API for determining likely gender from first names, full names, and email addresses. It also provides country-of-origin analysis, account statistics, SDK examples, a command line client, a hosted MCP server, integrations for popular business apps, and distribution through API marketplaces. New users can start with a free tier.

---

## ⚡ Start Here

- [AI implementation instructions (`skill.md`)](https://gender-api.com/skill.md): Prompt-ready instructions for AI assistants. Covers the main Gender-API v2 endpoints, authentication, request formats, responses, and implementation notes.
- [Unified API v2 documentation](https://gender-api.com/en/api-docs/v2): Best human-readable overview of the current API surface.
- [OpenAPI specification](https://gender-api.com/openapi/openapi.yml): Machine-readable API schema for Gender-API v2.
- [Swagger UI](https://gender-api.com/openapi/swagger/index.html): Interactive explorer for the OpenAPI definition.

---

## 🧬 Core API Reference & Expanded Endpoint Specs

Here are the direct endpoints along with full request/response schemas for inlined agent comprehension:

### 1. [Query by first name](https://gender-api.com/en/api-docs/v2/query-by-first-name): `POST /v2/gender` with `first_name`
Determine gender from first names with optional country localization for enhanced accuracy.

* **Headers**:
  * `Content-Type: application/json`
  * `Authorization: Bearer <your_api_token>`
* **Request Parameters**:
  * `first_name` (string, REQUIRED) - Name to query.
  * `country` (string, OPTIONAL) - ISO 3166 ALPHA-2 Country Code.
  * `locale` (string, OPTIONAL) - Browser Locale (e.g. `en_US`).
  * `ip` (string, OPTIONAL) - Valid IPv4 or IPv6 address.
  * `id` (string, OPTIONAL) - Max 50 chars alphanumeric tracker.
* **Request Example**:
  ```json
  {
    "first_name": "Sandra",
    "country": "US"
  }
  ```
* **Expected Response**:
  ```json
  {
    "input": {
      "first_name": "Sandra"
    },
    "details": {
      "credits_used": 1,
      "samples": 464,
      "country": "US",
      "first_name_sanitized": "sandra",
      "duration": "43ms"
    },
    "result_found": true,
    "first_name": "Sandra",
    "probability": 0.85,
    "gender": "female"
  }
  ```

---

### 2. [Query by full name](https://gender-api.com/en/api-docs/v2/query-by-full-name): `POST /v2/gender` with `full_name`
Automatically split full names and determine gender in one efficient API call.

* **Request Parameters**:
  * `full_name` (string, REQUIRED) - Full name to query.
  * `country` (string, OPTIONAL) - ISO 3166 ALPHA-2 Country Code.
  * `locale` (string, OPTIONAL) - Browser Locale.
  * `ip` (string, OPTIONAL) - Valid IPv4 or IPv6 address.
  * `id` (string, OPTIONAL) - Custom alphanumeric tracking ID.
* **Request Example**:
  ```json
  {
    "full_name": "Theresa Miller"
  }
  ```
* **Expected Response**:
  ```json
  {
    "input": {
      "full_name": "Theresa Miller"
    },
    "details": {
      "credits_used": 1,
      "duration": "33ms",
      "samples": 8961,
      "country": null,
      "first_name_sanitized": "theresa"
    },
    "result_found": true,
    "last_name": "Miller",
    "first_name": "Theresa",
    "probability": 0.98,
    "gender": "female"
  }
  ```

---

### 3. [Query by email address](https://gender-api.com/en/api-docs/v2/query-by-email-address): `POST /v2/gender` with `email`
Extract names from email addresses and determine gender with advanced parsing algorithms.

* **Request Parameters**:
  * `email` (string, REQUIRED) - Email address to query.
  * `country` (string, OPTIONAL) - ISO 3166 ALPHA-2 Country Code.
  * `locale` (string, OPTIONAL) - Browser Locale.
  * `ip` (string, OPTIONAL) - Valid IPv4 or IPv6 address.
  * `id` (string, OPTIONAL) - Custom alphanumeric tracking ID.
* **Request Example**:
  ```json
  {
    "email": "theresa.miller14@gmail.com"
  }
  ```
* **Expected Response**:
  ```json
  {
    "input": {
      "email": "theresa.miller14@gmail.com"
    },
    "details": {
      "credits_used": 1,
      "duration": "12ms",
      "samples": 8961,
      "country": null,
      "first_name_sanitized": "theresa"
    },
    "result_found": true,
    "last_name": "Miller",
    "first_name": "Theresa",
    "probability": 0.98,
    "gender": "female"
  }
  ```

---

### 4. [Country of origin](https://gender-api.com/en/api-docs/v2/country-of-origin): `POST /v2/country-of-origin`
Discover the likely country of origin, ethnicity distribution, and related metadata based on names.

* **Request Parameters**:
  * `first_name` (string, REQUIRED if `full_name` or `email` is not provided).
  * `full_name` (string, OPTIONAL) - Can be provided instead of `first_name`.
  * `email` (string, OPTIONAL) - Can be provided instead of `first_name`.
  * `id` (string, OPTIONAL) - Custom alphanumeric tracking ID.
* **Request Example**:
  ```json
  {
    "first_name": "Johann"
  }
  ```
* **Expected Response**:
  ```json
  {
    "input": {
      "first_name": "Johann",
      "id": 12
    },
    "details": {
      "credits_used": 2,
      "duration": "414ms",
      "samples": 890,
      "country": null,
      "first_name_sanitized": "johann"
    },
    "result_found": true,
    "country_of_origin": [
      {
        "country_name": "Germany",
        "country": "DE",
        "probability": 0.52,
        "continental_region": "Europe",
        "statistical_region": "Western Europe"
      },
      {
        "country_name": "Austria",
        "country": "AT",
        "probability": 0.48,
        "continental_region": "Europe",
        "statistical_region": "Western Europe"
      }
    ],
    "first_name": "Johann",
    "probability": 0.9,
    "gender": "male"
  }
  ```

---

### 5. [Statistics](https://gender-api.com/en/api-docs/v2/statistic): `GET /v2/statistic`
Retrieve detailed usage statistics and remaining request credits for your account.

* **Headers**:
  * `Authorization: Bearer <your_api_token>`
* **Expected Response**:
  ```json
  {
    "remaining_credits": 4983,
    "used_credits": 17
  }
  ```

### Additional Resources
- [Error codes](https://gender-api.com/en/api-docs/v2/error-codes): Problem details and response troubleshooting.
- [List of possible countries](https://gender-api.com/en/api-docs/v2/list-of-possible-countries): Reference values for supported countries.
- [List of possible ethnic groups](https://gender-api.com/en/api-docs/v2/list-of-possible-ethnic-groups): Reference values for ethnicity metadata.

---

## 🛠️ AI, Agent, and Automation Integrations

- [Hosted MCP Server](https://gender-api.com/en/app-integrations/mcp-server): Native MCP integration for Claude, Cursor, and other MCP-compatible clients. Hosted endpoint: `https://mcp.gender-api.com`.
  - For local development behind nginx, connect to: `http://localhost/mcp`.
- [Command Line Client](https://gender-api.com/en/app-integrations/cli-client): Official cross-platform command-line client for terminal workflows, automated scripting, and batch name-processing pipelines.
- [Postman Collection guide](https://gender-api.com/en/app-integrations/postman): Import and test the API quickly in Postman.
- [All app integrations](https://gender-api.com/en/app-integrations): Overview of supported integrations and workflow tools.

---

## 🔌 App Integrations

- [All app integrations](https://gender-api.com/en/app-integrations): Main overview page for app integrations across spreadsheets, CRMs, e-commerce, and marketing platforms.
- [Google Sheets](https://gender-api.com/en/app-integrations/google-sheets): Spreadsheet integration for enriching names directly in Google Sheets.
- [Zapier](https://gender-api.com/en/app-integrations/zapier): Connect Gender-API to automation workflows.
- [HubSpot](https://gender-api.com/en/app-integrations/hubspot): Enrich CRM contacts and leads.
- [Salesforce](https://gender-api.com/en/app-integrations/salesforce): Enrich Salesforce leads and contacts.
- [Shopify](https://gender-api.com/en/app-integrations/shopify): Enrich customer records for e-commerce personalization.
- [Mailchimp](https://gender-api.com/en/app-integrations/mailchimp): Enrich subscriber data for email marketing workflows.

---

## 🌐 API Marketplaces and Distribution

- [RapidAPI integration](https://gender-api.com/en/app-integrations/rapid-api): Marketplace distribution and onboarding through RapidAPI.
- [APILayer integration](https://gender-api.com/en/app-integrations/apilayer): Marketplace/distribution presence through APILayer.
- [APIs.json](https://gender-api.com/apis.json): Web API discovery metadata.

---

## 📦 SDKs and Code Examples

- [Client libraries overview](https://gender-api.com/en/clients): Entry point for official and community SDKs.
- [PHP examples](https://gender-api.com/en/code-examples/php): Composer-based PHP integration.
- [TypeScript examples](https://gender-api.com/en/code-examples/typescript): Type-safe JavaScript/TypeScript integration.
- [Python examples](https://gender-api.com/en/code-examples/python): Python client usage and examples.
- [Go examples](https://gender-api.com/en/code-examples/go): Go integration examples.
- [JavaScript examples](https://gender-api.com/en/code-examples/javascript): Browser and Node.js integration patterns.

---

## 🗃️ Machine-Readable Artifacts

- [OpenAPI YAML](https://gender-api.com/openapi/openapi.yml): Canonical API schema.
- [Swagger UI](https://gender-api.com/openapi/swagger/index.html): Interactive documentation based on the OpenAPI definition.
- [Postman Collection JSON](https://gender-api.com/openapi/Gender-API.com.postman_collection.json): Ready-to-import Postman collection.
- [APIs.json](https://gender-api.com/apis.json): Web API discovery metadata.

---

## 🔑 Authentication

- [API token management](https://gender-api.com/en/account/auth-tokens): Create and manage bearer tokens for API v2, CLI usage, and MCP integrations.
- Set the HTTP request header `Authorization: Bearer <your_token>`.

---

## 💳 Commercial and Onboarding Notes

- [Pricing](https://gender-api.com/en/pricing): Plan and pricing information, including the free tier if currently offered on the public site.
- Gender-API offers a free starting tier for new users; prefer the pricing page as the canonical source for current limits and plan details.

---

## 🤖 Guidance for Agents

- Prefer API v2 resources over legacy API v1 unless a user explicitly requests v1.
- Prefer `skill.md` for prompt-ready implementation guidance.
- Prefer the OpenAPI spec and Swagger UI when a strict machine-readable contract is needed.
- Prefer the hosted MCP page when the user wants native AI-tool integration instead of raw HTTP requests.
- Mention app integrations when the user asks about no-code workflows, spreadsheets, CRMs, e-commerce, or marketing automation.
- Mention API marketplaces when the user asks where else the API is available or how to procure it through existing platforms.
- Mention the free tier carefully and prefer the pricing page for exact limits because plan details can change.