ipwhois 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 439b7008b4082c53b21db0360b7d1b1914e890d069e43cbd451fae937a6768d6
+  data.tar.gz: f410bbc7ba36f0f3f0cecb0744ec1bbc3be19e98737bf064acee1b6be6f69395
+SHA512:
+  metadata.gz: 6fc2bb733df8f1a9fdee24b6cdb63e03aa6881e0a92b54ee33b894ed96a5ff547222ef8c5b30c12da39247df4226e21aba33a11a989f2ee54ce2d56680c6c529
+  data.tar.gz: 4188276ad8f840c73ef56b8a4623fc8fbb845b2f20af7961fb7ad2232a5457e047c20318c98baf5f0321352ba1157cccd22c5a35cc477149527893ce95624c13

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the `ipwhois` gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-05-12
+
+### Added
+
+- Initial public release of the `ipwhois` gem.
+- `Ipwhois::Client#lookup` — single IP lookup (IPv4 / IPv6, or current IP).
+- `Ipwhois::Client#bulk_lookup` — up to 100 IPs in a single GET request
+  (paid plan).
+- Free plan (no API key, `ipwho.is`) and paid plan (with API key,
+  `ipwhois.pro`) served by the same `Client` class.
+- HTTPS by default; `ssl: false` constructor option to fall back to HTTP.
+- Localisation (`:lang`), field filtering (`:fields`), threat detection
+  (`:security`), rate-limit info (`:rate`).
+- Fluent client-wide defaults: `set_language`, `set_fields`, `set_security`,
+  `set_rate`, `set_timeout`, `set_connect_timeout`, `set_user_agent` — each
+  returns `self` and is chainable.
+- **The library never raises.** All errors — invalid input, network failure,
+  API-level errors (bad IP, bad key, rate limit, …) — are returned in the
+  response hash with `'success' => false` and a `'message'`. HTTP error
+  responses are additionally enriched with `'http_status'`, and HTTP 429
+  responses on the free plan with `'retry_after'`.
+- Every error response carries an `'error_type'` field: one of `'api'`,
+  `'network'`, or `'invalid_argument'`, so callers can branch on the failure
+  category with a single `info['error_type']` check.
+- Minitest test suite covering URL construction, IPv6 path encoding, and
+  input validation. No real HTTP request is sent — the suite runs anywhere
+  without an API key or network access.
+- No runtime dependencies — uses only the Ruby stdlib (`net/http`, `uri`,
+  `json`, `openssl`).
+- Ruby `>= 3.0` requirement.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ipwhois.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,351 @@
+# ipwhois
+
+[![Gem Version](https://img.shields.io/gem/v/ipwhois.svg)](https://rubygems.org/gems/ipwhois)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0-blue.svg)](https://www.ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official, dependency-free Ruby client for the [ipwhois.io](https://ipwhois.io)
+IP Geolocation API.
+
+- ✅ Single and bulk IP lookups (IPv4 and IPv6)
+- ✅ Works with both the **Free** and **Paid** plans
+- ✅ HTTPS by default
+- ✅ Localisation, field selection, threat detection, rate info
+- ✅ Never raises — all errors returned as `'success' => false` hashes
+- ✅ No runtime dependencies — Ruby stdlib only (`net/http`, `uri`, `json`, `openssl`)
+- ✅ Ruby 3.0+
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'ipwhois'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install ipwhois
+```
+
+## Free vs Paid plan
+
+The same `Ipwhois::Client` class is used for both plans. The only difference is
+whether you pass an API key:
+
+- **Free plan** — create the client **without arguments**. No API key, no
+  signup required. Suitable for low-traffic and non-commercial use.
+- **Paid plan** — create the client **with your API key** from
+  <https://ipwhois.io>. Higher limits, plus access to bulk lookups and
+  threat-detection data.
+
+```ruby
+free = Ipwhois::Client.new               # Free plan — no API key
+paid = Ipwhois::Client.new('YOUR_API_KEY') # Paid plan — with API key
+```
+
+Everything else (`lookup`, options, error handling) is identical.
+
+## Quick start — Free plan (no API key)
+
+```ruby
+require 'ipwhois'
+
+client = Ipwhois::Client.new # no API key
+
+info = client.lookup('8.8.8.8')
+
+puts "#{info['country']} #{info.dig('flag', 'emoji')}"
+# → United States 🇺🇸
+
+puts "#{info['city']}, #{info['region']}"
+# → Mountain View, California
+```
+
+## Quick start — Paid plan (with API key)
+
+Get an API key at <https://ipwhois.io> and pass it to the constructor:
+
+```ruby
+require 'ipwhois'
+
+client = Ipwhois::Client.new('YOUR_API_KEY') # with API key
+
+info = client.lookup('8.8.8.8')
+
+puts "#{info['country']} #{info.dig('flag', 'emoji')}"
+# → United States 🇺🇸
+
+puts "#{info['city']}, #{info['region']}"
+# → Mountain View, California
+```
+
+> ℹ️ Pass nothing to look up your own public IP: `client.lookup` — works
+> on both plans.
+
+## Lookup options
+
+Every option below can be passed per call, or set once on the client as a
+default.
+
+| Option             | Type     | Plans needed         | Description                                                                |
+| ------------------ | -------- | -------------------- | -------------------------------------------------------------------------- |
+| `:lang`            | String   | Free + Paid          | One of: `'en'`, `'ru'`, `'de'`, `'es'`, `'pt-BR'`, `'fr'`, `'zh-CN'`, `'ja'` |
+| `:fields`          | Array    | Free + Paid          | Restrict the response to specific fields (e.g. `%w[country city]`)         |
+| `:rate`            | Boolean  | Basic and above      | Include the `rate` block (`limit`, `remaining`)                            |
+| `:security`        | Boolean  | Business and above   | Include the `security` block (proxy/vpn/tor/hosting)                       |
+
+### Setting defaults once
+
+Every option can be passed two ways: **per call** (as keyword arguments to
+`lookup` / `bulk_lookup`) or **once as a default** on the client. Per-call
+options always override the defaults, so it's safe to set sensible defaults
+and only override what differs for a specific call.
+
+Defaults are set with fluent setters — `set_language`, `set_fields`,
+`set_security`, `set_rate`, `set_timeout`, `set_connect_timeout`,
+`set_user_agent` — and can be chained:
+
+```ruby
+# Free plan
+client = Ipwhois::Client.new
+                       .set_language('en')
+                       .set_fields(%w[success country city flag.emoji])
+                       .set_timeout(8)
+```
+
+```ruby
+# Paid plan
+client = Ipwhois::Client.new('YOUR_API_KEY')
+                       .set_language('en')
+                       .set_fields(%w[success country city flag.emoji])
+                       .set_timeout(8)
+```
+
+Either client behaves the same way at call time — per-call options always
+win over the defaults:
+
+```ruby
+client.lookup('8.8.8.8')              # uses lang=en, the field whitelist, and timeout=8
+client.lookup('1.1.1.1', lang: 'de')  # overrides lang for this single call only
+```
+
+> ⚠️ When you restrict fields with `set_fields` (or the per-call `:fields`
+> option), the API only returns the fields you ask for. Always include
+> `'success'` in the list if you rely on `info['success']` for error
+> checking — otherwise the field will be missing on responses.
+
+> ℹ️ `set_security(true)` requires Business+ and `set_rate(true)` requires
+> Basic+. See the table above for what's available where.
+
+## HTTPS Encryption
+
+By default, all requests are sent over HTTPS. If you need to disable it (for
+example, in environments without an up-to-date CA bundle), pass `ssl: false`
+to the constructor:
+
+```ruby
+# Free plan
+client = Ipwhois::Client.new(nil, ssl: false)
+```
+
+```ruby
+# Paid plan
+client = Ipwhois::Client.new('YOUR_API_KEY', ssl: false)
+```
+
+> ℹ️ HTTPS is strongly recommended for production traffic — your API key is
+> sent in the query string and would otherwise travel in clear text.
+
+## Bulk lookup (Paid plan only)
+
+The bulk endpoint sends **up to 100 IPs** in a single GET request. Each
+address counts as one credit. Available on the **Business** and **Unlimited**
+plans.
+
+```ruby
+client = Ipwhois::Client.new('YOUR_API_KEY')
+
+results = client.bulk_lookup([
+  '8.8.8.8',
+  '1.1.1.1',
+  '208.67.222.222',
+  '2c0f:fb50:4003::'    # IPv6 is fine — mix freely
+])
+
+results.each do |row|
+  if row['success'] == false
+    # Per-IP errors (e.g. "Invalid IP address") are returned inline,
+    # they do NOT raise — the rest of the batch is still usable.
+    puts "skip #{row['ip']}: #{row['message']}"
+    next
+  end
+  puts "#{row['ip']} → #{row['country']}"
+end
+```
+
+> ℹ️ Bulk requires an API key. Calling `bulk_lookup` without one will fail
+> at the API level.
+
+## Error handling
+
+**The library never raises.** Every failure — invalid IP, bad API key, rate
+limit, network outage, bad options — comes back inside the response hash
+with `'success' => false` and a `'message'`. Just check `info['success']`
+after every call:
+
+```ruby
+info = client.lookup('8.8.8.8')
+
+unless info['success']
+  warn "Lookup failed: #{info['message']}"
+  return
+end
+
+puts info['country']
+```
+
+This means an outage of the ipwhois.io API (or of your server's DNS,
+connection, etc.) will never surface as a fatal error in your application —
+you decide how to react.
+
+### Error response fields
+
+Every error response contains `'success' => false`, a human-readable
+`'message'`, and an `'error_type'` so you can branch on the category of the
+failure. Some errors include extra fields you can branch on:
+
+| Field           | When it's present                                                                            |
+| --------------- | -------------------------------------------------------------------------------------------- |
+| `'success'`     | Always — false for error responses (true for successful responses)                           |
+| `'message'`     | Always — human-readable description of what went wrong                                       |
+| `'error_type'`  | Always — one of `'api'`, `'network'`, or `'invalid_argument'`                                |
+| `'http_status'` | On HTTP 4xx / 5xx responses                                                                  |
+| `'retry_after'` | On HTTP 429 — **free plan only** (the paid endpoint does not send a `Retry-After` header)    |
+
+```ruby
+info = client.lookup('8.8.8.8')
+
+unless info['success']
+  if info['http_status'] == 429
+    sleep(info['retry_after'] || 60)
+    # …retry
+  end
+  if info['error_type'] == 'network'
+    # DNS failure, connection refused, timeout, …
+  end
+  warn "Error: #{info['message']}"
+  return
+end
+```
+
+## Response shape
+
+A successful response includes (depending on your plan and selected options):
+
+```jsonc
+{
+    "ip": "8.8.4.4",
+    "success": true,
+    "type": "IPv4",
+    "continent": "North America",
+    "continent_code": "NA",
+    "country": "United States",
+    "country_code": "US",
+    "region": "California",
+    "region_code": "CA",
+    "city": "Mountain View",
+    "latitude": 37.3860517,
+    "longitude": -122.0838511,
+    "is_eu": false,
+    "postal": "94039",
+    "calling_code": "1",
+    "capital": "Washington D.C.",
+    "borders": "CA,MX",
+    "flag": {
+        "img": "https://cdn.ipwhois.io/flags/us.svg",
+        "emoji": "🇺🇸",
+        "emoji_unicode": "U+1F1FA U+1F1F8"
+    },
+    "connection": {
+        "asn": 15169,
+        "org": "Google LLC",
+        "isp": "Google LLC",
+        "domain": "google.com"
+    },
+    "timezone": {
+        "id": "America/Los_Angeles",
+        "abbr": "PDT",
+        "is_dst": true,
+        "offset": -25200,
+        "utc": "-07:00",
+        "current_time": "2026-05-08T14:31:48-07:00"
+    },
+    "currency": {
+        "name": "US Dollar",
+        "code": "USD",
+        "symbol": "$",
+        "plural": "US dollars",
+        "exchange_rate": 1
+    },
+    "security": {
+        "anonymous": false,
+        "proxy": false,
+        "vpn": false,
+        "tor": false,
+        "hosting": false
+    },
+    "rate": {
+        "limit": 250000,
+        "remaining": 50155
+    }
+}
+```
+
+Responses are parsed with the stdlib `JSON` module, so all hashes use **string
+keys** (`info['country']`, not `info[:country]`). Use `Hash#dig` for safe
+access to nested keys: `info.dig('flag', 'emoji')`.
+
+For the full field reference, see the [official documentation](https://ipwhois.io/documentation).
+
+An **error** response looks like:
+
+```jsonc
+{
+    "success": false,
+    "message": "Rate limit exceeded",
+    "error_type": "api",       // 'api' / 'network' / 'invalid_argument'
+    "http_status": 429,         // present for HTTP 4xx / 5xx
+    "retry_after": 60       // additionally present on HTTP 429 — free plan only
+}
+```
+
+## Requirements
+
+- Ruby **3.0** or newer
+- No runtime gem dependencies (uses stdlib only)
+
+## Development
+
+```bash
+git clone https://github.com/IPWhois/ipwhois-ruby.git
+cd ipwhois-ruby
+bundle install
+rake test
+```
+
+## Contributing
+
+Issues and pull requests are welcome on
+[GitHub](https://github.com/IPWhois/ipwhois-ruby).
+
+## License
+
+[MIT](LICENSE) © ipwhois.io

data/lib/ipwhois/client.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'openssl'
+
+module Ipwhois
+  # Ruby client for the ipwhois.io IP Geolocation API.
+  #
+  # Quick start
+  # -----------
+  #   # Free plan (no API key, ~1 request/second per client IP)
+  #   client = Ipwhois::Client.new
+  #   info   = client.lookup('8.8.8.8')
+  #
+  #   # Paid plan (with API key, higher limits, bulk, security data, …)
+  #   client = Ipwhois::Client.new('YOUR_API_KEY')
+  #   info   = client.lookup('8.8.8.8', lang: 'en', security: true)
+  #
+  #   # Bulk lookup — up to 100 IPs in one call (paid only)
+  #   list = client.bulk_lookup(['8.8.8.8', '1.1.1.1', '208.67.222.222'])
+  #
+  #   # HTTPS is enabled by default. Pass `ssl: false` to fall back to HTTP.
+  #
+  # Error handling
+  # --------------
+  # The library never raises. All errors — invalid input, network failure,
+  # API-level errors (bad IP, bad key, rate limit, …) — are returned in the
+  # response hash with `'success' => false` and a `'message'`. Just check
+  # `info['success']` after every call.
+  class Client
+    # Free-plan endpoint host (used when no API key is provided).
+    HOST_FREE = 'ipwho.is'
+
+    # Paid-plan endpoint host (used when an API key is provided).
+    HOST_PAID = 'ipwhois.pro'
+
+    # Maximum number of IP addresses allowed in a single bulk request.
+    BULK_LIMIT = 100
+
+    # Languages supported by the `lang` option.
+    SUPPORTED_LANGUAGES = %w[en ru de es pt-BR fr zh-CN ja].freeze
+
+    DEFAULT_TIMEOUT         = 10
+    DEFAULT_CONNECT_TIMEOUT = 5
+    MAX_REDIRECTS           = 3
+
+    # @param api_key [String, nil] Your ipwhois.io API key. Omit (or pass nil)
+    #   for the free plan.
+    # @param options [Hash] Optional defaults applied to every request.
+    #   Recognised keys: `:lang`, `:fields`, `:security`, `:rate`, `:ssl`,
+    #   `:timeout`, `:connect_timeout`, `:user_agent`.
+    def initialize(api_key = nil, **options)
+      @api_key         = api_key
+      @timeout         = options.delete(:timeout)         || DEFAULT_TIMEOUT
+      @connect_timeout = options.delete(:connect_timeout) || DEFAULT_CONNECT_TIMEOUT
+      @user_agent      = options.delete(:user_agent)      || "ipwhois-ruby/#{Ipwhois::VERSION}"
+      @ssl             = options.key?(:ssl) ? options.delete(:ssl) != false : true
+      @defaults        = options
+    end
+
+    # Look up information for a single IP address.
+    #
+    # Pass `nil` (or call without arguments) to look up the caller's own
+    # public IP, as documented at https://ipwhois.io/documentation.
+    #
+    # The library never raises — check `result['success']` after every call.
+    #
+    # @param ip [String, nil] IPv4 or IPv6 address. nil = current IP.
+    # @param options [Hash] Per-call options: `:lang`, `:fields`, `:security`,
+    #   `:rate`.
+    # @return [Hash] Decoded JSON response. On any error (API, network, bad
+    #   input) the hash contains `'success' => false` and `'message'`. The
+    #   library never raises.
+    def lookup(ip = nil, **options)
+      error = validate_options(options)
+      return error if error
+
+      path = ip.nil? ? '/' : "/#{escape_path_segment(ip.to_s)}"
+      url  = build_url(path, options)
+
+      request(url)
+    end
+
+    # Look up information for multiple IP addresses in a single request.
+    #
+    # Uses the GET / comma-separated form documented at
+    # https://ipwhois.io/documentation/bulk — up to 100 addresses per call.
+    # Each address counts as one credit.
+    #
+    # Available on the Business and Unlimited plans only.
+    #
+    # Per-IP errors are returned inline with `'success' => false` for the
+    # affected entry; the rest of the batch is still usable. If the whole
+    # call fails, the response is a single error hash with `'success' => false`
+    # instead of an array.
+    #
+    # @param ips [Array<String>] Up to 100 IPv4/IPv6 addresses (mixable).
+    # @param options [Hash] Per-call options (same keys as {#lookup}).
+    # @return [Array<Hash>, Hash] Array of per-IP results on success; a single
+    #   error hash on whole-batch failure. The library never raises.
+    def bulk_lookup(ips, **options)
+      unless ips.is_a?(Array)
+        return {
+          'success'    => false,
+          'message'    => 'Bulk lookup requires an Array of IP addresses.',
+          'error_type' => 'invalid_argument'
+        }
+      end
+
+      if ips.empty?
+        return {
+          'success'    => false,
+          'message'    => 'Bulk lookup requires at least one IP address.',
+          'error_type' => 'invalid_argument'
+        }
+      end
+
+      if ips.size > BULK_LIMIT
+        return {
+          'success'    => false,
+          'message'    => "Bulk lookup accepts at most #{BULK_LIMIT} IP addresses per call, got #{ips.size}.",
+          'error_type' => 'invalid_argument'
+        }
+      end
+
+      error = validate_options(options)
+      return error if error
+
+      # The API accepts addresses joined by commas — no URL-encoding of the
+      # commas themselves, otherwise the path is misinterpreted.
+      joined = ips.map { |ip| escape_path_segment(ip.to_s) }.join(',')
+      url    = build_url("/bulk/#{joined}", options)
+
+      request(url)
+    end
+
+    # Set the default language used when none is supplied per call.
+    #
+    # @param lang [String] One of {SUPPORTED_LANGUAGES}.
+    # @return [self]
+    def set_language(lang)
+      @defaults[:lang] = lang
+      self
+    end
+
+    # Restrict every response to a fixed set of fields by default.
+    #
+    # Include `'success'` in the list if you rely on `info['success']` for
+    # error checking — when `:fields` is set, the API only returns the fields
+    # you ask for.
+    #
+    # @param fields [Array<String>] For example: %w[success country city flag.emoji].
+    # @return [self]
+    def set_fields(fields)
+      @defaults[:fields] = fields
+      self
+    end
+
+    # Enable or disable threat-detection data on every call by default.
+    # @return [self]
+    def set_security(enabled)
+      @defaults[:security] = enabled
+      self
+    end
+
+    # Enable or disable the `rate` block in responses by default.
+    # @return [self]
+    def set_rate(enabled)
+      @defaults[:rate] = enabled
+      self
+    end
+
+    # Set the per-request total timeout in seconds (default: 10).
+    # @return [self]
+    def set_timeout(seconds)
+      @timeout = seconds
+      self
+    end
+
+    # Set the connection timeout in seconds (default: 5).
+    # @return [self]
+    def set_connect_timeout(seconds)
+      @connect_timeout = seconds
+      self
+    end
+
+    # Override the User-Agent header sent with every request.
+    # @return [self]
+    def set_user_agent(user_agent)
+      @user_agent = user_agent
+      self
+    end
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    private
+
+    # Validate per-call options. Returns an error hash on the first invalid
+    # option, or nil if everything looks OK.
+    def validate_options(options)
+      merged = @defaults.merge(options)
+
+      if merged[:lang]
+        lang = merged[:lang].to_s
+        unless SUPPORTED_LANGUAGES.include?(lang)
+          return {
+            'success'    => false,
+            'message'    => "Unsupported language \"#{lang}\". Supported: #{SUPPORTED_LANGUAGES.join(', ')}.",
+            'error_type' => 'invalid_argument'
+          }
+        end
+      end
+
+      nil
+    end
+
+    # Build the full URL for a given path + options.
+    def build_url(path, options)
+      host = @api_key ? HOST_PAID : HOST_FREE
+
+      # Per-call options win over defaults.
+      merged = @defaults.merge(options)
+
+      query = []
+      query << ['key', @api_key]                if @api_key
+      query << ['lang', merged[:lang].to_s]     if merged[:lang]
+
+      if merged[:fields]
+        fields_value = merged[:fields].is_a?(Array) ? merged[:fields].join(',') : merged[:fields].to_s
+        query << ['fields', fields_value]
+      end
+
+      query << ['security', '1'] if merged[:security]
+      query << ['rate', '1']     if merged[:rate]
+
+      scheme = @ssl ? 'https' : 'http'
+      url    = "#{scheme}://#{host}#{path}"
+      url   += "?#{URI.encode_www_form(query)}" unless query.empty?
+      url
+    end
+
+    # RFC 3986 percent-encoding for a single path segment — encodes
+    # everything outside unreserved chars, in particular the `:` characters
+    # in IPv6 addresses, which would otherwise be interpreted as a port
+    # separator by URI parsers.
+    def escape_path_segment(str)
+      str.gsub(/([^A-Za-z0-9\-._~])/) { |c| format('%%%02X', c.ord) }
+    end
+
+    # Perform a GET request and return the decoded JSON body.
+    def request(url)
+      uri = URI.parse(url)
+
+      http_response = perform_http_get(uri, MAX_REDIRECTS)
+      # On network failure perform_http_get returns a pre-shaped error hash.
+      return http_response if http_response.is_a?(Hash)
+
+      status_code = http_response.code.to_i
+      body        = http_response.body.to_s
+
+      decoded =
+        if body.empty?
+          nil
+        else
+          begin
+            JSON.parse(body)
+          rescue JSON::ParserError
+            # The ipwhois API always returns JSON. A non-JSON body means
+            # something went wrong upstream (gateway error page, captive
+            # portal, hijacked response, …) — synthesise an error hash so
+            # the caller can handle it the same way as a normal API error.
+            snippet = body.gsub(/\s+/, ' ').strip
+            snippet = "#{snippet[0, 200]}…" if snippet.length > 200
+            return {
+              'success'     => false,
+              'message'     => "Invalid JSON returned by ipwhois API (HTTP #{status_code}): #{snippet}",
+              'http_status' => status_code,
+              'error_type'  => 'api'
+            }
+          end
+        end
+
+      # Normalise plain values into a hash so the rest of the pipeline can
+      # treat the result uniformly. Arrays (bulk responses) are passed
+      # through as-is.
+      decoded = {} if decoded.nil?
+      decoded = { 'value' => decoded } unless decoded.is_a?(Hash) || decoded.is_a?(Array)
+
+      # For HTTP errors, normalise into a `success => false` hash so the
+      # caller doesn't have to inspect HTTP status separately.
+      if status_code >= 400
+        if decoded.is_a?(Hash) && decoded['success'] == false
+          # The API already shaped the error correctly — just enrich it.
+          decoded['http_status'] = status_code
+        else
+          message = (decoded.is_a?(Hash) && decoded['message']) ||
+                    "HTTP #{status_code} returned by ipwhois API"
+          decoded = {
+            'success'     => false,
+            'message'     => message,
+            'http_status' => status_code
+          }
+        end
+
+        # `Retry-After` is only emitted by the free-plan endpoint
+        # (ipwho.is); the paid endpoint (ipwhois.pro) does not send the
+        # header, so don't try to read it there.
+        if status_code == 429 && @api_key.nil?
+          retry_after = http_response['retry-after']
+          decoded['retry_after'] = retry_after.to_i if retry_after
+        end
+      end
+
+      # Tag every API-shaped error (`success => false` returned by the API,
+      # on any HTTP status) with `error_type => 'api'` so callers can branch
+      # on the category alongside the non-API codes ('network',
+      # 'invalid_argument'). HTTP 2xx + success=false bodies (e.g. "Invalid
+      # IP address", "Reserved range") are otherwise passed through
+      # untouched.
+      if decoded.is_a?(Hash) && decoded['success'] == false && !decoded.key?('error_type')
+        decoded['error_type'] = 'api'
+      end
+
+      decoded
+    end
+
+    # Perform the actual HTTP GET. Follows up to `redirects_left` redirects.
+    # Returns either a Net::HTTPResponse or a pre-shaped error hash on
+    # network/transport failure.
+    def perform_http_get(uri, redirects_left)
+      use_ssl           = (uri.scheme == 'https')
+      http              = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = use_ssl
+      http.verify_mode  = OpenSSL::SSL::VERIFY_PEER if use_ssl
+      http.open_timeout = @connect_timeout
+      http.read_timeout = @timeout
+
+      req               = Net::HTTP::Get.new(uri.request_uri)
+      req['User-Agent'] = @user_agent
+      req['Accept']     = 'application/json'
+
+      response = http.request(req)
+
+      if response.is_a?(Net::HTTPRedirection) && redirects_left.positive?
+        location = response['location']
+        return network_error('redirect without Location header') if location.nil? || location.empty?
+
+        new_uri = URI.parse(location)
+        # Location headers may be relative — resolve against the current URI.
+        new_uri = uri + location unless new_uri.absolute?
+        return perform_http_get(new_uri, redirects_left - 1)
+      end
+
+      response
+    rescue Net::OpenTimeout => e
+      network_error("connection timeout: #{e.message}")
+    rescue Net::ReadTimeout => e
+      network_error("read timeout: #{e.message}")
+    rescue SocketError => e
+      network_error(e.message)
+    rescue OpenSSL::SSL::SSLError => e
+      network_error("SSL error: #{e.message}")
+    rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+           Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError => e
+      network_error(e.message)
+    end
+
+    def network_error(message)
+      {
+        'success'    => false,
+        'message'    => "Network error: #{message}",
+        'error_type' => 'network'
+      }
+    end
+  end
+end

data/lib/ipwhois/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Ipwhois
+  # Gem version, used in the default User-Agent header.
+  VERSION = '1.2.0'
+end

data/lib/ipwhois.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'ipwhois/version'
+require_relative 'ipwhois/client'
+
+# Top-level namespace for the ipwhois.io IP Geolocation API client.
+#
+# Quick start
+# -----------
+#   # Free plan (no API key, ~1 request/second per client IP)
+#   client = Ipwhois::Client.new
+#   info   = client.lookup('8.8.8.8')
+#
+#   # Paid plan (with API key, higher limits, bulk, security data, …)
+#   client = Ipwhois::Client.new('YOUR_API_KEY')
+#   info   = client.lookup('8.8.8.8', lang: 'en', security: true)
+#
+#   # Bulk lookup — up to 100 IPs in one call (paid only)
+#   list = client.bulk_lookup(['8.8.8.8', '1.1.1.1', '208.67.222.222'])
+#
+#   # HTTPS is enabled by default. Pass `ssl: false` to fall back to HTTP.
+#
+# Error handling
+# --------------
+# The library never raises. All errors — invalid input, network failure,
+# API-level errors (bad IP, bad key, rate limit, …) — are returned in the
+# response hash with `'success' => false` and a `'message'`. Just check
+# `info['success']` after every call.
+module Ipwhois
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: ipwhois
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- ipwhois.io
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Simple, dependency-free Ruby client for the ipwhois.io IP Geolocation
+  API. Supports single and bulk IP lookups (IPv4 and IPv6), free and paid plans, localisation,
+  field selection, threat detection and rate-limit info.
+email:
+- support@ipwhois.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ipwhois.rb
+- lib/ipwhois/client.rb
+- lib/ipwhois/version.rb
+homepage: https://ipwhois.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://ipwhois.io
+  source_code_uri: https://github.com/IPWhois/ipwhois-ruby
+  bug_tracker_uri: https://github.com/IPWhois/ipwhois-ruby/issues
+  documentation_uri: https://ipwhois.io/documentation
+  changelog_uri: https://github.com/IPWhois/ipwhois-ruby/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby client for the ipwhois.io IP Geolocation API.
+test_files: []