openapi: 3.0.7
info:
  title: 'IPGeolocation.io: Abuse Contact ASN Lookup IP Security API'
  version: '3.0'
  description: "Retrieve abuse contact information associated with an IPv4 address or IPv6 address.\nThe API returns the organization responsible for handling abuse complaints related\nto the queried IP address, including the abuse contact role, organization name,\nregistered address, email contacts, and phone numbers.\n\nThe abuse contact data helps organizations report malicious activities such as\nspam, phishing, DDoS attacks, IP spoofing, and other network abuse to the\nresponsible network operator.\n\nOne endpoint is available:\n\n- **Abuse lookup** (`GET /v3/abuse`) returns abuse contact information for a\n  single IPv4 or IPv6 address per request.\n\nUse query parameters to control which fields are returned and which fields are\nexcluded from the response to reduce payload size when only specific data\nis required.\n\n## Authentication\n\nTwo authentication methods are supported:\n\n### API Key\n\nPass your API key as the `apiKey` query parameter on every request. You can find your\nkey in the [IPGeolocation dashboard](https://app.ipgeolocation.io/). Store it in\nserver-side environment variables. Avoid exposing it in client-side JavaScript.\n\n### Request Origin (CORS)\n\nAvailable on paid plans only. Whitelist your domain in the dashboard under the\n\"API Keys\" section. Once configured, requests from that domain (and all its subdomains)\nare accepted without passing `apiKey`. Enter your root domain (e.g. `example.com`),\nnot the full URL.\n\nEach plan has a limit on the number of extra API keys and request origins:\n\n| Plan | Extra API Keys + Request Origins |\n|---|---|\n| Starter (150K requests) | 1 |\n| Core (250K requests) | 1 |\n| Plus (500K requests) | 2 |\n| Pro (1M requests) | 2 |\n| Business (2M requests) | 3 |\n| Premium (5M requests) | 3 |\n\nAdditional keys or origins can be added for $2.50 per month each.\n\n## Response Formats\n\nThe API supports JSON (default) and XML output.\n\n- Set the `output` query parameter to `json` or `xml`.\n- Alternatively, set the `Accept` header to `application/json`, `application/xml`,\n  or `text/xml`.\n\nIf neither is specified, the response is returned as JSON. XML responses use a\n`LinkedHashMap` root element.\n\n## Credit Usage\n\nCredits are charged only for successful **HTTP 200** responses. The exact number of\ncredits consumed by a request is returned in the `X-Credits-Charged` response header.\n\nA **single IP abuse contact lookup** (`GET /v3/abuse`) consumes **1 credit** per request.\n\n\n## Field Filtering\n\nUse `fields` to cherry-pick specific fields, or `excludes` to drop fields you do not\nneed. Both accept dot-notation for nested fields (e.g. `abuse.route`,\n`abuse.organization`). The `ip` field is always present regardless of filters.\n\n## Parameter Name Casing\n\nQuery parameter names are case-sensitive. Use exact names such as\n`apiKey`, `ip`, `fields`, `excludes`, and `output`.\n\n## Plan Availability and Usage Limits\n\nThe IP Abuse Contact API is available **only on paid plans**.\n\nPaid subscriptions do not have fixed daily, hourly, or monthly rate limits.  \nIf the monthly quota is exceeded, requests continue and a surcharge may be applied according to the subscribed plan.\n\nFree plans cannot access the IP Abuse Contact API. Requests made with a free plan API key return **HTTP 401 Unauthorized**.\n"
  contact:
    name: IPGeolocation Support
    url: https://ipgeolocation.io/contact.html
    email: support@ipgeolocation.io
  termsOfService: https://ipgeolocation.io/tos.html
  license:
    name: Proprietary
    url: https://ipgeolocation.io/tos.html
servers:
- url: https://api.ipgeolocation.io
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: IP Security
  description: 'IP security intelligence endpoints used to detect VPNs,

    proxies, Tor exit nodes, relay networks, bot activity,

    spam activity, cloud providers, and other anonymization

    technologies associated with IP addresses.


    The single lookup endpoint (`GET /v3/security`) analyzes

    one IP per request.


    The bulk lookup endpoint (`POST /v3/security-bulk`)

    accepts up to 50,000 IP addresses per request.

    '
  externalDocs:
    description: IPGeolocation IP Security API documentation
    url: https://ipgeolocation.io/documentation/ip-security-api.html
paths:
  /v3/security:
    get:
      operationId: lookupIpSecurity
      summary: IPGeolocation.io Single IP Security Lookup
      description: 'Returns threat intelligence and anonymization signals for a single

        IPv4 or IPv6 address.


        If the `ip` parameter is omitted, the API automatically detects the

        caller''s public IP address and returns its security risk signals.


        The response includes a threat score and multiple indicators such

        as VPN usage, proxy usage, Tor exit node detection, relay networks,

        bot activity, spam activity, and cloud hosting infrastructure.


        When available, provider names, confidence scores, and last-seen

        timestamps are included.


        Use the `fields` and `excludes` parameters to control which parts

        of the response are returned.

        '
      tags:
      - IP Security
      parameters:
      - $ref: '#/components/parameters/Ip'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Excludes'
      - $ref: '#/components/parameters/Output'
      responses:
        '200':
          description: Security intelligence for the requested IP.
          headers:
            X-Credits-Charged:
              description: Number of API credits consumed by this request.
              schema:
                type: number
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpSecurityResponse'
              example:
                security:
                  threat_score: 80
                  is_tor: false
                  is_proxy: true
                  proxy_provider_names:
                  - Zyte Proxy
                  proxy_confidence_score: 80
                  proxy_last_seen: '2025-12-12'
                  is_residential_proxy: true
                  is_vpn: true
                  vpn_provider_names:
                  - Nord VPN
                  vpn_confidence_score: 80
                  vpn_last_seen: '2026-01-19'
                  is_relay: false
                  relay_provider_name: ''
                  is_anonymous: true
                  is_known_attacker: true
                  is_bot: false
                  is_spam: false
                  is_cloud_provider: true
                  cloud_provider_name: Packethub S.A.
            application/xml:
              schema:
                $ref: '#/components/schemas/IpSecurityResponse'
              example: "<LinkedHashMap>\n  <ip>2.56.188.34</ip>\n  <security>\n      <threat_score>80</threat_score>\n      <is_tor>false</is_tor>\n      <is_proxy>true</is_proxy>\n      <proxy_provider_names>Zyte Proxy</proxy_provider_names>\n      <proxy_confidence_score>80</proxy_confidence_score>\n      <proxy_last_seen>2025-12-12</proxy_last_seen>\n      <is_residential_proxy>true</is_residential_proxy>\n      <is_vpn>true</is_vpn>\n      <vpn_provider_names>Nord VPN</vpn_provider_names>\n      <vpn_confidence_score>80</vpn_confidence_score>\n      <vpn_last_seen>2026-01-19</vpn_last_seen>\n      <is_relay>false</is_relay>\n      <relay_provider_name></relay_provider_name>\n      <is_anonymous>true</is_anonymous>\n      <is_known_attacker>true</is_known_attacker>\n      <is_bot>false</is_bot>\n      <is_spam>false</is_spam>\n      <is_cloud_provider>true</is_cloud_provider>\n      <cloud_provider_name>Packethub S.A.</cloud_provider_name>\n  </security>\n</LinkedHashMap>\n"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '499':
          $ref: '#/components/responses/ClientClosedRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '505':
          $ref: '#/components/responses/HttpVersionNotSupported'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/security-bulk:
    post:
      operationId: bulkLookupIpSecurity
      summary: IPGeolocation.io Bulk IP Security Lookup
      description: 'Returns security intelligence for up to **50,000 IPv4 or IPv6

        addresses** in a single request.


        The request body must contain an `ips` array.


        Each IP is processed independently. Invalid, bogon, or private

        IP addresses return an object containing only a `message` field.


        Credits are charged **per valid IP address** using the same

        pricing rules as the single lookup endpoint.


        When at least one entry is invalid, the response header

        `X-Successful-Record` indicates the number of successful

        lookups.


        Only the `POST` method is supported for this endpoint.

        '
      tags:
      - IP Security
      parameters:
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/Excludes'
      - $ref: '#/components/parameters/Output'
      requestBody:
        required: true
        description: 'A JSON object containing an `ips` array. Each element is a string representing

          an IPv4 address or IPv6 address. The array must not be empty and

          must not contain more than 50,000 entries.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSecurityRequest'
            examples:
              mixedIps:
                summary: Mixed IPv4 and IPv6
                value:
                  ips:
                  - 8.8.8.8
                  - 91.128.103.196
                  - 2607:fb91:16c6:8860:e531:2d1d:4944:6c7c
              ipv4Only:
                summary: Multiple IPv4 addresses
                value:
                  ips:
                  - 1.1.1.1
                  - 8.8.4.4
                  - 165.227.0.0
      responses:
        '200':
          description: 'An array of results, one per input IP address.


            Valid entries return a security lookup object containing the IP address

            and its associated security intelligence.


            Invalid, private, or bogon IP addresses return an object containing only

            a `message` field.


            The `X-Successful-Record` response header is returned only when the request

            contains one or more invalid entries and indicates the number of successful

            lookups.

            '
          headers:
            X-Credits-Charged:
              description: 'Total number of API credits consumed. Equals credits per lookup

                multiplied by the count of valid IPs.

                '
              schema:
                type: number
                example: 3
            X-Successful-Record:
              description: 'Number of valid IP addresses that were successfully resolved in

                this bulk request. Invalid, bogon, and private IPs are not counted.

                This header is included only when at least one bulk entry returns an

                error message and total successful lookups are fewer than submitted

                entries.

                '
              schema:
                type: number
                example: 4
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkSecurityResponseItem'
              example:
              - ip: 2.56.188.34
                security:
                  threat_score: 80
                  is_tor: false
                  is_proxy: true
                  proxy_provider_names:
                  - Zyte Proxy
                  proxy_confidence_score: 80
                  proxy_last_seen: '2025-12-12'
                  is_residential_proxy: true
                  is_vpn: true
                  vpn_provider_names:
                  - Nord VPN
                  vpn_confidence_score: 80
                  vpn_last_seen: '2026-01-19'
                  is_relay: false
                  relay_provider_name: ''
                  is_anonymous: true
                  is_known_attacker: true
                  is_bot: false
                  is_spam: false
                  is_cloud_provider: true
                  cloud_provider_name: Packethub S.A.
              - message: '''10.0.0.1'' is a bogon IP address.'
            application/xml:
              schema:
                type: array
                xml:
                  name: ArrayList
                  wrapped: true
                items:
                  $ref: '#/components/schemas/BulkSecurityResponseItem'
                  xml:
                    name: item
              example: "<ArrayList>\n  <item>\n    <ip>2.56.188.34</ip>\n    <security>\n        <threat_score>80</threat_score>\n        <is_tor>false</is_tor>\n        <is_proxy>true</is_proxy>\n        <proxy_provider_names>Zyte Proxy</proxy_provider_names>\n        <proxy_confidence_score>80</proxy_confidence_score>\n        <proxy_last_seen>2025-12-12</proxy_last_seen>\n        <is_residential_proxy>true</is_residential_proxy>\n        <is_vpn>true</is_vpn>\n        <vpn_provider_names>Nord VPN</vpn_provider_names>\n        <vpn_confidence_score>80</vpn_confidence_score>\n        <vpn_last_seen>2026-01-19</vpn_last_seen>\n        <is_relay>false</is_relay>\n        <relay_provider_name></relay_provider_name>\n        <is_anonymous>true</is_anonymous>\n        <is_known_attacker>true</is_known_attacker>\n        <is_bot>false</is_bot>\n        <is_spam>false</is_spam>\n        <is_cloud_provider>true</is_cloud_provider>\n        <cloud_provider_name>Packethub S.A.</cloud_provider_name>\n    </security>\n  <item>\n      <message>'10.0.0.0' is a bogon IP address.</message>\n  </item>\n</ArrayList>\n"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '499':
          $ref: '#/components/responses/ClientClosedRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
        '505':
          $ref: '#/components/responses/HttpVersionNotSupported'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    BulkSecurityErrorItem:
      type: object
      description: 'Error object returned for an invalid entry in the bulk lookup request. Contains only

        a `message` field. Note: unlike success entries, error entries do NOT include the

        original `ip` field, so the only way to correlate errors to inputs is by array

        index. The response array preserves the same order as the request `ips` array.

        '
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable error for the specific bulk entry.
          example: Provided name, service or IP address 'invalid-ip' is not valid.
    BulkSecurityResponseItem:
      description: 'A single element in the bulk lookup response array. Each element is either a

        full security object or an error object containing only `message`.

        '
      oneOf:
      - $ref: '#/components/schemas/BulkSecuritySuccessItem'
      - $ref: '#/components/schemas/BulkSecurityErrorItem'
    Security:
      type: object
      description: 'Threat intelligence and anonymization signals for the IP. Costs 2 credits.

        '
      properties:
        threat_score:
          type: number
          description: 'Overall threat score from 0 (clean) to 100 (high risk). Aggregated from

            all the individual signals below.

            '
          minimum: 0
          maximum: 100
          example: 80
        is_tor:
          type: boolean
          description: Whether the IP is a known Tor exit node.
          example: false
        is_proxy:
          type: boolean
          description: Whether the IP belongs to a known proxy service.
          example: true
        proxy_provider_names:
          type: array
          description: Names of proxy providers associated with this IP, if any.
          items:
            type: string
          examples:
          - Zyte Proxy
        proxy_confidence_score:
          type: number
          description: 'Confidence that this IP is a proxy, from 0 to 100. Only meaningful when

            `is_proxy` is `true`.

            '
          minimum: 0
          maximum: 100
          example: 90
        proxy_last_seen:
          type: string
          description: 'Date when this IP was last observed acting as a proxy, in `YYYY-MM-DD`

            format. Empty string if never seen.

            '
          example: '2025-12-12'
        is_residential_proxy:
          type: boolean
          description: Whether the IP is a known residential proxy.
          example: true
        is_vpn:
          type: boolean
          description: Whether the IP belongs to a known VPN provider.
          example: true
        vpn_provider_names:
          type: array
          description: Names of VPN providers associated with this IP, if any.
          items:
            type: string
          examples:
          - Nord VPN
        vpn_confidence_score:
          type: number
          description: 'Confidence that this IP is a VPN endpoint, from 0 to 100. Only meaningful

            when `is_vpn` is `true`.

            '
          minimum: 0
          maximum: 100
          example: 90
        vpn_last_seen:
          type: string
          description: 'Date when this IP was last observed as a VPN endpoint, in `YYYY-MM-DD`

            format. Empty string if never seen.

            '
          example: '2026-01-19'
        is_relay:
          type: boolean
          description: Whether the IP is part of a known relay network (e.g. iCloud Private Relay).
          example: false
        relay_provider_name:
          type: string
          description: Name of the relay provider, if any. Empty string if not a relay.
          example: ''
        is_anonymous:
          type: boolean
          description: 'Whether the IP is associated with any anonymization method (VPN, proxy,

            Tor, or relay).

            '
          example: true
        is_known_attacker:
          type: boolean
          description: Whether the IP has been flagged in known attacker or threat feeds.
          example: true
        is_bot:
          type: boolean
          description: Whether the IP is associated with known bot activity.
          example: false
        is_spam:
          type: boolean
          description: Whether the IP is listed in spam databases.
          example: false
        is_cloud_provider:
          type: boolean
          description: Whether the IP belongs to a cloud hosting or data center provider.
          example: true
        cloud_provider_name:
          type: string
          description: Name of the cloud provider, if applicable. Empty string otherwise.
          example: Packethub S.A.
    IpSecurityResponse:
      type: object
      xml:
        name: LinkedHashMap
      required:
      - ip
      properties:
        ip:
          type: string
          description: IP address used for the lookup.
          example: 2.56.188.34
        security:
          $ref: '#/components/schemas/Security'
    BulkSecuritySuccessItem:
      type: object
      required:
      - ip
      - security
      properties:
        ip:
          type: string
          description: IP address for this lookup result.
          example: 2.56.188.34
        security:
          $ref: '#/components/schemas/Security'
    ErrorResponse:
      type: object
      description: 'Returned for any non-200 response. Contains only a human-readable `message`.

        Message text can vary by status and condition; examples in this spec are

        representative, not exhaustive, and should not be treated as stable machine

        codes.

        '
      required:
      - message
      properties:
        message:
          type: string
          description: Human-readable explanation of what went wrong. Use HTTP status for control flow.
          example: Provided name, service or IP address '999.999.999.999' is not valid.
    BulkSecurityRequest:
      type: object
      description: 'Request body for the bulk security lookup. Contains a single `ips` field

        with an array of IP addresses to look up.

        '
      required:
      - ips
      properties:
        ips:
          type: array
          description: 'Array of IPv4 addresses or IPv6 addresses to look up.

            Must not be empty. Maximum 50,000 entries per request. Each entry is

            resolved independently, so you can mix IPv4 and IPv6 freely.

            '
          minItems: 1
          maxItems: 50000
          items:
            type: string
          examples:
          - 8.8.8.8
          - 91.128.103.196
          - 2607:fb91:16c6:8860:e531:2d1d:4944:6c7c
  responses:
    BadRequest:
      description: "Bad request. Returned for one of the following reasons:\n\n- The provided IPv4 or IPv6 address is invalid.\n- Special characters such as ( ) [ ] { } | ^ ` are present in the API URL,\n  either in a parameter name or its value (especially in the API key).\n- For the `security-bulk` endpoint:\n  - The request payload is empty or missing.\n  - The JSON body is malformed.\n  - The `ips` field is missing or the `ips` array is empty.\n  - More than 50,000 IP addresses are provided in the request.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidIp:
              summary: Invalid IPv4/IPv6 input
              value:
                message: Provided name, service or IP address '999.999.999.999' is not valid.
            specialCharacters:
              summary: Special characters in API URL or key
              value:
                message: Invalid character found in the request target.
            malformedJson:
              summary: Malformed JSON body for bulk endpoint
              value:
                message: Malformed JSON request or invalid field
            missingIps:
              summary: Bulk body missing ips field
              value:
                message: IP addresses for bulk lookup are missing
            emptyBulkIps:
              summary: Bulk ips array is empty
              value:
                message: '''ips'' must not be empty or null'
            tooManyBulkEntries:
              summary: Bulk body exceeds 50,000 entries
              value:
                message: No. of lookup queries cannot be more than 50000
    NotFound:
      description: "Not found. Returned for one of the following reasons:\n\n- A syntactically valid IPv4 or IPv6 address does not exist in the IPGeolocation database.\n- An IPv4 address, IPv6 address, or domain name is passed as a path variable\n  instead of as a URL query parameter (e.g., using `/v3/ipgeo/8.8.8.8`\n  instead of `/v3/ipgeo?ip=8.8.8.8`).\n- A non-existent or incorrect API endpoint is called.\n\nInvalid or malformed IPv4, IPv6, or domain input returns HTTP 400 instead.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            ipNotInDatabase:
              summary: IPv4/IPv6 not found in database
              value:
                message: Provided IPv4 or IPv6 address does not exist in our database.
            ipAsPathVariable:
              summary: IP passed as path variable instead of query parameter
              value:
                message: No endpoint GET /v3/ipgeo/8.8.8.8.
            wrongEndpoint:
              summary: Incorrect or non-existent endpoint
              value:
                message: No endpoint GET /v3/security-invalid.
    HttpVersionNotSupported:
      description: 'HTTP Version Not Supported. The server does not support the HTTP protocol

        version used in the request.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: HTTP version not supported.
    PayloadTooLarge:
      description: 'Payload too large. Returned by the edge proxy (nginx) when raw POST body size

        exceeds configured limits before the request reaches the application.


        This status is based on payload byte size, not on the number of IP entries. It

        can occur even when `ips` contains only one very large value.


        If both conditions apply (oversized body and `ips` count > 50,000), HTTP 413 may

        be returned first because edge validation runs before application-level checks.

        '
      content:
        text/html:
          schema:
            type: string
          example: "<html>\n  <head>\n    <title>413 Request Entity Too Large</title>\n  </head>\n  <body>\n    <center><h1>413 Request Entity Too Large</h1></center>\n    <hr><center>nginx/1.24.0 (Ubuntu)</center>\n  </body>\n</html>\n"
    MethodNotAllowed:
      description: 'Method Not Allowed. Returned when an unsupported HTTP method is used

        to call an endpoint.


        Only GET and POST methods are supported:


        - `GET` is allowed for the `ipgeo` endpoint.

        - `POST` is allowed for the `ipgeo-bulk` endpoint.


        Any other HTTP method, or using the correct method on the wrong endpoint,

        results in HTTP 405.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            getNotAllowedForBulk:
              summary: GET used on bulk endpoint
              value:
                message: Request method 'GET' is not supported
            postNotAllowedForSingle:
              summary: POST used on single lookup endpoint
              value:
                message: Request method 'POST' is not supported
            unsupportedMethod:
              summary: Unsupported HTTP method
              value:
                message: Request method is not supported
    Locked:
      description: 'Locked. The provided IP address belongs to a bogon IP range or a private

        network and cannot be looked up.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: '''10.0.0.1'' is a bogon IP address.'
    ServiceUnavailable:
      description: 'Service Unavailable. The API is temporarily unavailable due to maintenance

        or overload. Please try again later.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Service temporarily unavailable. Please try again later.
    BadGateway:
      description: 'Bad Gateway. The API server received an invalid response from an upstream

        server while processing the request. This is usually temporary.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Upstream service error. Please try again later.
    Unauthorized:
      description: "Unauthorized. Returned for one of the following reasons:\n\n- The `apiKey` URL parameter is missing.\n- An invalid (random or incorrect) API key is provided.\n- The account has been disabled or locked due to abuse or illegal activity.\n- The API request is made using an API key for a database subscription.\n- The API request is made using a free subscription API key.\n- The subscription is in a 'paused' state.\n- The subscription trial has expired.\n- The account’s active-until date has passed and renewal or upgrade is required.\n- A domain name is passed in the `ip` parameter when calling the IP Security API.\n- The bulk IP security lookup endpoint is called using a free subscription API key.\n- The bulk IP security lookup endpoint is called using Request Origin (CORS)\n  authentication. Bulk requests require an `apiKey` and cannot be authenticated\n  using Request Origin alone.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                message: Please provide an API key (as 'apiKey=YOUR_API_KEY' URL parameter) to use IPGeolocation API. To get your free API Key, sign up at https://app.ipgeolocation.io/login
            invalidApiKey:
              summary: Invalid API key
              value:
                message: Provided API key is not valid. Contact technical support for assistance at support@ipgeolocation.io
            lockedAccount:
              summary: Account locked or disabled
              value:
                message: Your account has been locked to use IPGeolocation API. Contact technical support for assistance at support@ipgeolocation.io
            databaseSubscriptionKey:
              summary: Database subscription API key used for REST API
              value:
                message: You cannot query IPGeolocation API on a database plan subscription.
            freePlanAccess:
              summary: Free subscription used for IP Security API
              value:
                message: IP Security API is not supported on your current subscription. This feature is available on paid subscriptions only.
            pausedSubscription:
              summary: Subscription is paused
              value:
                message: Your subscription has been paused. Please resume your subscription to use IPGeolocation API.
            expiredSubscription:
              summary: Subscription expired or trial ended
              value:
                message: Your subscription has expired. Please subscribe to a paid plan to continue using IPGeolocation API.
            domainLookupNotSupported:
              summary: Domain lookup used with Security API
              value:
                message: Domain lookup is not supported for the IP Security API.
            requestOriginBulk:
              summary: Bulk endpoint called using Request Origin authentication
              value:
                message: Bulk queries are not allowed with request origins. Please use an API key to perform bulk queries.
    ClientClosedRequest:
      description: 'The client closed the connection before the server finished processing the

        request. This usually happens when the client sets a very short request or

        connection timeout. Increase the timeout on the client side.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Client closed the request before the server could respond.
    UnsupportedMediaType:
      description: 'Unsupported media type. The `Content-Type` header is not set to `application/json`.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Content-Type 'application/x-www-form-urlencoded' is not supported
    GatewayTimeout:
      description: 'Gateway Timeout. The API server did not receive a timely response from

        an upstream server.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: The server timed out while processing the request.
    TooManyRequests:
      description: "Too Many Requests. Returned for one of the following reasons:\n- The API usage limit has been reached for a Paid subscription with\n  status 'past due', 'deleted', or 'trial expired'.\n- The surcharge API usage limit has been reached for the subscribed plan.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            usageLimitReached:
              summary: API usage limit reached
              value:
                message: You have exceeded the limit of PLAN_USAGE_LIMIT requests per PLAN_INERVAL for your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption.
            surchargeLimitReached:
              summary: Surcharge usage limit reached
              value:
                message: You have reached the surcharge amount limit of PLAN_USAGE_LIMIT_AND_SURCHARGE_LIMIT on your subscribed PLAN plan. Please throttle your requests or upgrade your plan to continue using IPGeolocation API without interruption.
    InternalServerError:
      description: 'Internal Server Error. The server encountered an unexpected condition

        that prevented it from fulfilling the request. If the issue persists,

        contact support@ipgeolocation.io.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: Something went wrong on the server side.
  parameters:
    Fields:
      name: fields
      in: query
      required: false
      description: 'Comma-separated list of fields or objects to return. Everything else is omitted.

        The `ip` field is always returned regardless of this filter.


        Supports dot-notation for nested fields: `security.is_tor`, `security.threat_score`.


        If the same field or object is specified in both `fields` and `excludes`, the

        object is still returned, but it will be empty.


        If you list both an object key and one of its nested fields separated by comma

        (e.g. `security,security.is_vpn`), the full object is returned.


        Unknown field paths are ignored. The API still returns HTTP 200.


        Available on all plans including Free.

        '
      schema:
        type: string
      examples:
        none:
          summary: Return the full response (no field filtering)
          value: ''
        threatScoreOnly:
          summary: Return only the threat score
          value: security.threat_score
        moreThanOneFields:
          summary: Return specific fields
          value: security.is_tor,security.is_vpn
    Ip:
      name: ip
      in: query
      required: false
      description: 'An IPv4 address or IPv6 address to look up. When omitted, the API

        resolves the public IP of the requesting client. Empty or whitespace-only values

        are treated the same as omission and resolve caller IP. Pass `ip` only once. If multiple `ip` query parameters are sent,

        values may be merged and treated as invalid input (HTTP 400).

        '
      schema:
        type: string
      examples:
        ipv4:
          summary: IPv4 address
          value: 91.128.103.196
        ipv6:
          summary: IPv6 address
          value: 2607:fb91:16c6:8860:e531:2d1d:4944:6c7c
    Excludes:
      name: excludes
      in: query
      required: false
      description: 'Comma-separated list of fields or objects to remove from the response. The `ip`

        field cannot be excluded.


        Supports dot-notation for nested fields: `security.is_relay`.


        If the same field or object is specified in both `fields` and `excludes`, the

        object is still returned, but it will be empty.


        Unknown fields or object keys in `excludes` are ignored. The API still returns

        HTTP 200.


        Available on all plans including Free.

        '
      schema:
        type: string
      examples:
        none:
          summary: Do not exclude any fields
          value: ''
        excludeFields:
          summary: Exclude proxy provider names and residential proxy flag
          value: security.proxy_provider_names,security.is_residential_proxy
    Output:
      name: output
      in: query
      required: false
      description: 'Desired response format. Defaults to `json` if not specified. You can also

        control the format using the `Accept` header (`application/json`,

        `application/xml`, or `text/xml`). If both are provided, the `output` parameter

        takes precedence.


        If `output` is unknown or unsupported, it is ignored and the response defaults

        to JSON (`application/json`) with HTTP 200.

        '
      schema:
        type: string
        enum:
        - json
        - xml
        default: json
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: apiKey
      description: 'API key passed as the `apiKey` query parameter. Get yours from the

        [IPGeolocation dashboard](https://app.ipgeolocation.io/). For client-side

        usage, consider using Request Origin (CORS) authentication instead to

        avoid exposing your key.

        '
externalDocs:
  description: IPGeolocation Abuse Contact API documentation
  url: https://ipgeolocation.io/documentation/ip-abuse-contact-api.html