Genderize.io Gender Prediction API

openapi: 3.0.3
info:
  title: Genderize.io Gender Prediction API
  description: 'Free REST API that predicts the gender of a first name with probability scores based on name statistics from millions of users worldwide. Part of the Demografix suite alongside Agify (age prediction) and Nationalize (nationality prediction), sharing a single API key across all three services.

    '
  version: 1.0.0
  contact:
    url: https://genderize.io
  license:
    name: Commercial / Free Tier
    url: https://genderize.io/pricing
servers:
- url: https://api.genderize.io
  description: Production API server
tags:
- name: Gender Prediction
  description: Predict the gender of one or more first names.
paths:
  /:
    get:
      operationId: predictGender
      summary: Predict gender for a name or batch of names
      description: 'Accepts a single first name or up to 10 names in a batch and returns gender predictions (male, female, or null) along with probability scores and sample counts. Optionally scoped to a specific country using an ISO 3166-1 alpha-2 country code.

        '
      tags:
      - Gender Prediction
      parameters:
      - name: name
        in: query
        description: 'Single first name to predict gender for. Mutually exclusive with the batch form `name[]`.

          '
        required: false
        schema:
          type: string
          example: James
      - name: name[]
        in: query
        description: 'Batch of first names (up to 10). Repeat the parameter for each name, e.g. `?name[]=James&name[]=Mary`.

          '
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
          maxItems: 10
          example:
          - James
          - Mary
      - name: country_id
        in: query
        description: 'Two-letter ISO 3166-1 alpha-2 country code used to localize predictions to a specific country''s naming conventions.

          '
        required: false
        schema:
          type: string
          pattern: ^[A-Z]{2}$
          example: US
      - name: apikey
        in: query
        description: 'API key obtained from the account dashboard. Required for more than 100 names per day (free tier) or to access paid plan quotas.

          '
        required: false
        schema:
          type: string
          example: abc123def456
      responses:
        '200':
          description: Successful gender prediction response.
          headers:
            X-Rate-Limit-Limit:
              description: Total number of names allowed in the current rate-limit window.
              schema:
                type: integer
            X-Rate-Limit-Remaining:
              description: Number of names remaining in the current rate-limit window.
              schema:
                type: integer
            X-Rate-Limit-Reset:
              description: Seconds until the current rate-limit window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/GenderPrediction'
                - type: array
                  items:
                    $ref: '#/components/schemas/GenderPrediction'
              examples:
                single:
                  summary: Single name prediction
                  value:
                    name: james
                    gender: male
                    probability: 0.98
                    count: 3547638
                batch:
                  summary: Batch name prediction
                  value:
                  - name: james
                    gender: male
                    probability: 0.98
                    count: 3547638
                  - name: mary
                    gender: female
                    probability: 0.99
                    count: 2164301
                withCountry:
                  summary: Country-scoped prediction
                  value:
                    name: andrea
                    gender: female
                    probability: 0.74
                    count: 312845
                unknownGender:
                  summary: Name with unknown gender
                  value:
                    name: xyz
                    gender: null
                    probability: null
                    count: 0
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid API key
        '402':
          description: Subscription limit reached or payment required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Request limit reached
        '422':
          description: Unprocessable request — missing or invalid parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Missing 'name' parameter
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Request limit reached
components:
  schemas:
    GenderPrediction:
      type: object
      description: Gender prediction result for a single name.
      properties:
        name:
          type: string
          description: The name as processed by the API.
          example: james
        gender:
          type: string
          nullable: true
          enum:
          - male
          - female
          description: 'Predicted gender. Null when there is insufficient data to make a prediction.

            '
          example: male
        probability:
          type: number
          format: float
          nullable: true
          minimum: 0
          maximum: 1
          description: 'Confidence score for the gender prediction, between 0 and 1. Null when gender is null.

            '
          example: 0.98
        count:
          type: integer
          description: 'Number of data samples used to make the prediction. A higher count generally indicates a more reliable prediction.

            '
          example: 3547638
      required:
      - name
      - gender
      - probability
      - count
    ErrorResponse:
      type: object
      description: Error response returned for 4xx status codes.
      properties:
        error:
          type: string
          description: Human-readable description of the error.
          example: Missing 'name' parameter
      required:
      - error