openapi: 3.1.0
info:
  title: iplookupapi
  version: "2"
  summary: IP geolocation, ASN and hosted-domain lookups.
  description: >-
    ipbase resolves IP addresses to geolocation, network (ASN), security and
    hosted-domain data. 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 ipbase service implementation and is the
    machine-readable source of truth for the v2 REST API. A human-readable
    version is available at https://iplookupapi.com/docs.
  contact:
    name: iplookupapi support
    email: support@iplookupapi.com
    url: https://support.iplookupapi.com/
  x-logo:
    url: https://iplookupapi.com/iplookupapi_logo.svg
servers:
  - url: https://api.iplookupapi.com
    description: Production
security:
  - ApiKeyQuery: []
  - ApiKeyHeader: []
tags:
  - name: Lookup
    description: IP, ASN and hosted-domain lookups.
  - name: Metadata
    description: Account status.
paths:
  /v1/info:
    get:
      tags:
        - Lookup
      summary: Look up an IP address
      operationId: getInfo
      description: >-
        Returns geolocation, network, timezone, security and hosted-domain data
        for an IP address. When `ip` is omitted, the caller's own IP is used.
      parameters:
        - name: ip
          in: query
          required: false
          description: >-
            The IPv4 or IPv6 address to look up. Defaults to the requesting
            client's IP when omitted.
          schema:
            type: string
          example: "1.1.1.1"
        - name: language
          in: query
          required: false
          description: Language for translated location names.
          schema:
            type: string
            enum: [de, en, es, fr, ja, pt, ru, zh]
            default: en
        - name: hostname
          in: query
          required: false
          description: >-
            When `true`, performs a reverse-DNS lookup and includes the
            `hostname` field. May add latency.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: IP lookup result.
          headers:
            X-RateLimit-Limit-Quota-Month:
              $ref: '#/components/headers/RateLimitLimitQuotaMonth'
            X-RateLimit-Remaining-Quota-Month:
              $ref: '#/components/headers/RateLimitRemainingQuotaMonth'
            X-Cost:
              $ref: '#/components/headers/Cost'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResponse'
              example:
                data:
                  ip: "1.1.1.1"
                  hostname: "one.one.one.one"
                  type: "v4"
                  range_type:
                    type: "PUBLIC"
                    description: "Public address"
                  connection:
                    asn: 13335
                    organization: "Cloudflare, Inc."
                    isp: "APNIC Research and Development"
                    range: "1.1.1.1/32"
                  location:
                    geonames_id: 5368753
                    latitude: 34.053611755371094
                    longitude: -118.24549865722656
                    zip: "90012"
                    continent:
                      code: "NA"
                      name: "North America"
                      name_translated: "North America"
                    country:
                      alpha2: "US"
                      alpha3: "USA"
                      calling_codes: ["+1"]
                      emoji: "🇺🇸"
                      name: "United States"
                      name_translated: "United States"
                      is_in_european_union: false
                    city:
                      name: "Los Angeles"
                      name_translated: "Los Angeles"
                    region:
                      alpha2: "US-CA"
                      name: "California"
                      name_translated: "California"
                  tlds: [".us"]
                  timezone:
                    id: "America/Los_Angeles"
                    current_time: "2023-06-28T07:46:37-07:00"
                    code: "PDT"
                    is_daylight_saving: true
                    gmt_offset: -25200
                  security:
                    is_anonymous: false
                    is_datacenter: false
                    is_vpn: false
                    is_bot: false
                    is_abuser: false
                    is_known_attacker: false
                    is_proxy: false
                    is_spam: false
                    is_tor: false
                    is_icloud_relay: false
                    threat_score: 100
                  domains:
                    count: 12337
                    domains:
                      - "eliwise.academy"
                      - "accountingprose.academy"
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/status:
    get:
      tags:
        - Metadata
      summary: Account quota status
      operationId: getStatus
      description: >-
        Returns your current monthly and grace quota usage. Requests to this
        endpoint do not count against your quota or rate limit.
      responses:
        '200':
          description: Current quota usage for the authenticated account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              example:
                account_id: 313373133731337
                quotas:
                  month: { total: 300, used: 72, remaining: 228 }
                  grace: { total: 0, used: 0, remaining: 0 }
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as the `apikey` query parameter.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: >-
        API key passed as the `apikey` request header. Recommended, as it keeps
        the key out of URLs and access logs.
  headers:
    RateLimitLimitQuotaMonth:
      description: Your monthly request quota.
      schema: { type: integer }
      example: 300
    RateLimitRemainingQuotaMonth:
      description: Remaining requests in your monthly quota.
      schema: { type: integer }
      example: 228
    Cost:
      description: Requests this call counted against your quota.
      schema: { type: integer }
      example: 1
  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."
    Forbidden:
      description: Your plan does not include this endpoint.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example:
            message: "You are not allowed to use the ASN endpoint, please upgrade your plan"
            info: "For more information, see documentation: https://iplookupapi.com/docs/status-codes#_403"
    NotFound:
      description: No data was found for the requested IP or ASN.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
          example:
            message: "No data found for this IP"
            info: "For more information, see documentation: https://iplookupapi.com/docs/status-codes#_404"
    ValidationError:
      description: One or more request parameters failed validation.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ValidationError' }
          example:
            message: "Validation error"
            errors:
              ip:
                - "The ip must be a valid IP address."
            info: "For more information, see documentation: https://iplookupapi.com/docs/status-codes#_422"
    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:
    InfoResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/IpInfo'
      required: [data]
    IpInfo:
      type: object
      properties:
        ip:
          type: string
          example: "1.1.1.1"
        hostname:
          type: [string, "null"]
          description: Reverse-DNS hostname; only populated when `hostname=true`.
          example: "one.one.one.one"
        type:
          type: string
          enum: [v4, v6]
        range_type:
          type: object
          properties:
            type: { type: string, example: "PUBLIC" }
            description: { type: string, example: "Public address" }
        connection:
          type: object
          properties:
            asn: { type: integer, example: 13335 }
            organization: { type: string, example: "Cloudflare, Inc." }
            isp: { type: string, example: "APNIC Research and Development" }
            range: { type: string, example: "1.1.1.1/32" }
        location:
          $ref: '#/components/schemas/Location'
        tlds:
          type: array
          items: { type: string }
          example: [".us"]
        timezone:
          type: object
          properties:
            id: { type: string, example: "America/Los_Angeles" }
            current_time: { type: string, example: "2023-06-28T07:46:37-07:00" }
            code: { type: string, example: "PDT" }
            is_daylight_saving: { type: boolean }
            gmt_offset: { type: integer, example: -25200 }
        security:
          type: object
          properties:
            is_anonymous: { type: boolean }
            is_datacenter: { type: boolean }
            is_vpn: { type: boolean }
            is_bot: { type: boolean }
            is_abuser: { type: boolean }
            is_known_attacker: { type: boolean }
            is_proxy: { type: boolean }
            is_spam: { type: boolean }
            is_tor: { type: boolean }
            is_icloud_relay: { type: boolean }
            threat_score: { type: integer, example: 100 }
        domains:
          type: object
          properties:
            count: { type: integer, example: 12337 }
            domains:
              type: array
              items: { type: string }
      required: [ip, type]
    Location:
      type: object
      properties:
        geonames_id: { type: [integer, "null"] }
        latitude: { type: number, example: 34.0536 }
        longitude: { type: number, example: -118.2455 }
        zip: { type: [string, "null"], example: "90012" }
        continent:
          type: object
          properties:
            code: { type: string, example: "NA" }
            name: { type: string, example: "North America" }
            name_translated: { type: string, example: "North America" }
        country:
          type: object
          properties:
            alpha2: { type: string, example: "US" }
            alpha3: { type: string, example: "USA" }
            calling_codes:
              type: array
              items: { type: string }
              example: ["+1"]
            emoji: { type: string, example: "🇺🇸" }
            name: { type: string, example: "United States" }
            name_translated: { type: string, example: "United States" }
            is_in_european_union: { type: boolean }
        city:
          type: object
          properties:
            name: { type: [string, "null"], example: "Los Angeles" }
            name_translated: { type: [string, "null"], example: "Los Angeles" }
        region:
          type: object
          properties:
            alpha2: { type: [string, "null"], example: "US-CA" }
            name: { type: [string, "null"], example: "California" }
            name_translated: { type: [string, "null"], example: "California" }
    AsnResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            asn: { type: string, example: "13335" }
            organization: { type: string, example: "Cloudflare, Inc." }
            domain: { type: [string, "null"], example: "cloudflare.com" }
            country: { type: [string, "null"], example: "US" }
            isp: { type: [string, "null"], example: "Cloudflare, Inc." }
            ip_count: { type: integer, example: 1543168 }
            ranges_count: { type: integer, example: 2 }
            ranges:
              type: array
              items:
                type: object
                properties:
                  subnet: { type: string, example: "1.1.1.0/24" }
                additionalProperties: true
      required: [data]
    DomainsResponse:
      type: object
      properties:
        data:
          type: array
          items: { type: string }
        total_count: { type: integer, example: 12337 }
        per_page: { type: integer, example: 30 }
        next_cursor: { type: [string, "null"] }
        next_page_url: { type: [string, "null"] }
        prev_page_url: { type: [string, "null"] }
      required: [data, total_count]
    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: 300 }
        used: { type: integer, example: 72 }
        remaining: { type: integer, example: 228 }
    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]
