openapi: 3.1.0
info:
  title: freeiplookupapi
  version: "1"
  summary: Free IP geolocation lookup.
  description: >-
    freeiplookupapi resolves an IP address to basic geolocation data (country,
    region, city, postal code, timezone and coordinates). All endpoints are
    served over HTTPS and return JSON. Authenticate every request with your API
    key, either as the `apikey` query parameter or the `apikey` request header.


    This document is generated from the freeiplookupapi service implementation
    and is the machine-readable source of truth for the v1 REST API. A
    human-readable version is available at https://freeiplookupapi.com/docs.
    freeiplookupapi is the free tier of ipbase.com — upgrade there for ASN,
    hosted domains, security signals and richer location data.
  contact:
    name: freeiplookupapi support
    email: support@freeiplookupapi.com
servers:
  - url: https://api.freeiplookupapi.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Lookup
    description: IP geolocation.
  - name: Metadata
    description: Account status.
paths:
  /v1/info:
    get:
      tags: [Lookup]
      summary: Look up an IP address
      operationId: getInfo
      description: >-
        Returns basic geolocation data for an IP address. When `ip` is omitted,
        the caller's own IP is used. Unknown IPs return the same shape with empty
        strings and zeroed coordinates.
      parameters:
        - name: ip
          in: query
          required: false
          description: The IPv4 or IPv6 address to look up. Defaults to the caller's IP.
          schema: { type: string }
          example: "1.1.1.1"
      responses:
        '200':
          description: Geolocation result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IpInfo' }
              example:
                ip: "1.1.1.1"
                country_code: "US"
                country_name: "United States"
                region_code: "US-CA"
                region_name: "California"
                city: "Los Angeles"
                postal_code: "90012"
                time_zone: "America/Los_Angeles"
                latitude: 34.05
                longitude: -118.25
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/ValidationError' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /v1/status:
    get:
      tags: [Metadata]
      summary: Account quota status
      operationId: getStatus
      description: Returns your quota usage. Does not count against your quota.
      responses:
        '200':
          description: Current quota usage.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/StatusResponse' }
              example:
                account_id: 313373133731337
                quotas:
                  month: { total: 5000, used: 120, remaining: 4880 }
                  grace: { total: 0, used: 0, remaining: 0 }
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    ApiKeyQuery: { type: apiKey, in: query, name: apikey, description: "API key as the apikey query parameter." }
    ApiKeyHeader: { type: apiKey, in: header, name: apikey, description: "API key as the apikey request header (recommended)." }
  responses:
    Unauthorized:
      description: An API key was supplied but is invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "If you specify an apikey it has to be a valid one." }
    ValidationError:
      description: The supplied IP address is invalid.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }
          example:
            message: "Validation error"
            errors: { ip: ["The ip must be a valid IP address."] }
    RateLimited:
      description: You have exceeded your monthly quota or minute rate limit.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example: { message: "You have reached your monthly limit, please upgrade your plan" }
  schemas:
    IpInfo:
      type: object
      properties:
        ip: { type: string, example: "1.1.1.1" }
        country_code: { type: string, example: "US" }
        country_name: { type: string, example: "United States" }
        region_code: { type: string, example: "US-CA" }
        region_name: { type: string, example: "California" }
        city: { type: string, example: "Los Angeles" }
        postal_code: { type: string, example: "90012" }
        time_zone: { type: string, example: "America/Los_Angeles" }
        latitude: { type: number, example: 34.05 }
        longitude: { type: number, example: -118.25 }
      required:
        - ip
        - country_code
        - country_name
        - region_code
        - region_name
        - city
        - postal_code
        - time_zone
        - latitude
        - longitude
    StatusResponse:
      type: object
      properties:
        account_id: { type: integer, example: 313373133731337 }
        quotas:
          type: object
          properties:
            month: { $ref: '#/components/schemas/QuotaBucket' }
            grace: { $ref: '#/components/schemas/QuotaBucket' }
          required: [month]
      required: [quotas]
    QuotaBucket:
      type: object
      properties:
        total: { type: integer, example: 5000 }
        used: { type: integer, example: 120 }
        remaining: { type: integer, example: 4880 }
    Error:
      type: object
      properties: { message: { type: string }, info: { type: string } }
      required: [message]
    ValidationError:
      type: object
      properties:
        message: { type: string, example: "Validation error" }
        errors:
          type: object
          additionalProperties: { type: array, items: { type: string } }
        info: { type: string }
      required: [message, errors]
