openapi: 3.0.3
info:
  title: IPWho API
  description: Enterprise-grade IP Intelligence API providing rich geolocation, timezone, currency, and security data.
  version: 1.0.0
servers:
  - url: https://api.ipwho.org
paths:
  /ip/{ip}:
    get:
      summary: Get IP Geolocation Data
      description: Returns detailed information for a specific IPv4 or IPv6 address.
      parameters:
        - name: ip
          in: path
          required: true
          description: The IP address to look up.
          schema:
            type: string
            example: "8.8.8.8"
        - name: apiKey
          in: query
          required: true
          description: Your API key for authentication.
          schema:
            type: string
            example: "sk.xxxx"
        - name: format
          in: query
          required: false
          description: The desired response format.
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
        - name: get
          in: query
          required: false
          description: A comma-separated list of specific fields or objects to return.
          schema:
            type: string
            example: "geoLocation,timezone"
      responses:
        '200':
          description: Successful IP lookup.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpGeoResponse'
            application/xml:
              schema:
                type: string
            text/csv:
              schema:
                type: string
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Invalid IP or not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /me:
    get:
      summary: Get Current User's IP Data
      description: Automatically detects the visitor's IP address and returns its geolocation data.
      parameters:
        - name: apiKey
          in: query
          required: true
          description: Your API key for authentication.
          schema:
            type: string
            example: "sk.xxxx"
      responses:
        '200':
          description: Successful lookup of the current IP.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpGeoResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /bulk/{bulkIP}:
    get:
      summary: Bulk IP Lookup
      description: Perform geolocation lookups for multiple IP addresses in a single request.
      parameters:
        - name: bulkIP
          in: path
          required: true
          description: A comma-separated list of IP addresses.
          schema:
            type: string
            example: "8.8.8.8,1.1.1.1"
        - name: apiKey
          in: query
          required: true
          description: Your API key for authentication.
          schema:
            type: string
            example: "sk.xxxx"
      responses:
        '200':
          description: Successful bulk IP lookup.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      responseArray:
                        type: array
                        items:
                          $ref: '#/components/schemas/IpGeoResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  schemas:
    IpGeoResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            ip:
              type: string
            geoLocation:
              type: object
              properties:
                continent:
                  type: string
                  nullable: true
                continentCode:
                  type: string
                  nullable: true
                country:
                  type: string
                  nullable: true
                countryCode:
                  type: string
                  nullable: true
                capital:
                  type: string
                  nullable: true
                region:
                  type: string
                  nullable: true
                regionCode:
                  type: string
                  nullable: true
                city:
                  type: string
                  nullable: true
                postal_Code:
                  type: string
                  nullable: true
                dial_code:
                  type: string
                  nullable: true
                is_in_eu:
                  type: boolean
                latitude:
                  type: number
                  nullable: true
                longitude:
                  type: number
                  nullable: true
                accuracy_radius:
                  type: number
                  nullable: true
            timezone:
              type: object
              properties:
                time_zone:
                  type: string
                  nullable: true
                abbr:
                  type: string
                  nullable: true
                offset:
                  type: number
                  nullable: true
                is_dst:
                  type: boolean
                  nullable: true
                utc:
                  type: string
                  nullable: true
                current_time:
                  type: string
                  nullable: true
            flag:
              type: object
              properties:
                flag_Icon:
                  type: string
                  nullable: true
                flag_unicode:
                  type: string
                  nullable: true
            currency:
              type: object
              properties:
                code:
                  type: string
                symbol:
                  type: string
                name:
                  type: string
                name_plural:
                  type: string
                hex_unicode:
                  type: string
            connection:
              type: object
              properties:
                asn_number:
                  type: number
                  nullable: true
                asn_org:
                  type: string
                  nullable: true
                isp:
                  type: string
                  nullable: true
                org:
                  type: string
                  nullable: true
                domain:
                  type: string
                  nullable: true
                connection_type:
                  type: string
                  nullable: true
            security:
              type: object
              properties:
                isVpn:
                  type: boolean
                isTor:
                  type: boolean
                isThreat:
                  type: string
                  enum: [low, medium, high]
            userAgent:
              type: object
              properties:
                browser:
                  type: object
                  properties:
                    name:
                      type: string
                    version:
                      type: string
                engine:
                  type: object
                  properties:
                    name:
                      type: string
                    version:
                      type: string
                os:
                  type: object
                  properties:
                    name:
                      type: string
                    version:
                      type: string
                device:
                  type: object
                  properties:
                    type:
                      type: string
                    vendor:
                      type: string
                    model:
                      type: string
                cpu:
                  type: object
                  properties:
                    architecture:
                      type: string
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Invalid API key"