openapi: 3.0.3
info:
  title: Genderize.io 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