openapi: 3.0.3
info:
  title: Gender API
  description: >-
    Gender-API determines whether a first name is more likely used by males or
    females, with optional localization by country, IP address, or browser
    locale. The API returns a gender prediction and an accuracy score, and
    supports email parsing, multi-name lookup, and country-of-origin queries.
  version: '2.0'
  contact:
    name: Gender-API Support
    url: https://gender-api.com/en/contact
  license:
    name: Gender-API Terms of Service
    url: https://gender-api.com/en/terms-and-conditions
servers:
  - url: https://gender-api.com
    description: Gender-API production endpoint
security:
  - apiKey: []
paths:
  /get:
    get:
      summary: Get gender for a name
      description: >-
        Returns a gender prediction (male, female, or unknown) for the supplied
        first name with an accuracy score. Supports localization by country,
        IP, or locale, and parsing of full names or email addresses.
      operationId: getGender
      parameters:
        - name: name
          in: query
          description: First name (or full name with split=true) to look up. Supports semicolon-separated lists when multi=true.
          schema:
            type: string
        - name: email
          in: query
          description: Email address from which to extract the name.
          schema:
            type: string
            format: email
        - name: country
          in: query
          description: ISO 3166-1 alpha-2 country code to localize the lookup.
          schema:
            type: string
        - name: ip
          in: query
          description: Client IP address used to localize the lookup.
          schema:
            type: string
        - name: locale
          in: query
          description: Browser locale (e.g. en_US, de_DE) used to localize the lookup.
          schema:
            type: string
        - name: split
          in: query
          description: When true, splits a full name and resolves the first name automatically.
          schema:
            type: boolean
        - name: multi
          in: query
          description: When true, accepts a semicolon-separated list of names (max 100 per request).
          schema:
            type: boolean
        - name: key
          in: query
          required: true
          description: Gender-API key (alternatively send via apiKey query or Authorization header per account configuration).
          schema:
            type: string
      responses:
        '200':
          description: Gender prediction result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenderResponse'
        '401':
          description: Missing or invalid API key
        '429':
          description: Rate limit or credit limit exceeded
  /get-country-of-origin:
    get:
      summary: Get likely country of origin for a name
      description: Returns the most likely country (or list of countries) of origin for the supplied first or last name. Costs more credits per query than /get.
      operationId: getCountryOfOrigin
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
        - name: key
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Country of origin prediction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryOfOriginResponse'
  /get-stats:
    get:
      summary: Get account statistics
      description: Returns account information including remaining credits, plan details, and usage statistics for the supplied API key.
      operationId: getStats
      parameters:
        - name: key
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Account statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatsResponse'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
  schemas:
    GenderResponse:
      type: object
      properties:
        name:
          type: string
        gender:
          type: string
          enum: [male, female, unknown]
        samples:
          type: integer
        accuracy:
          type: integer
          minimum: 0
          maximum: 100
        credits_used:
          type: integer
        duration:
          type: string
    CountryOfOriginResponse:
      type: object
      properties:
        name:
          type: string
        country_of_origin:
          type: array
          items:
            type: object
            properties:
              country:
                type: string
              probability:
                type: number
        credits_used:
          type: integer
        duration:
          type: string
    StatsResponse:
      type: object
      properties:
        remaining_requests:
          type: integer
        is_limit_reached:
          type: boolean
        server_time:
          type: string