ip-api-io 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76f9eb0fbe4f73944dc67a95f4ab308518ec21ddc45a42d339d262c3d06a3e2d
+  data.tar.gz: 77b408c2f71dd4353a8a7f92188e5bd1ddfb593039c8932d952313d2b9bfb634
+SHA512:
+  metadata.gz: e282e89c5e72ee6c4e8bbbd9d65a4d98c507f0782924d8b223f0630858d28ea6e900083121d0350c160f76770540b39057dc69e2d4c25520ad4cd92f8928220e
+  data.tar.gz: 5d28ce14fd0bcf17a009a09a3917df78bec8e8bae124dc5648f9ffd767a7fce47db659bf1699e8f46dc8b3cc8f3d6a167473dae2fe8ece3d72a386208a268277

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [1.0.0] - 2026-06-12
+
+### Added
+- Initial release: full client for the ip-api.io v1 API — IP geolocation and
+  threat intelligence (single + batch), email validation (basic, advanced,
+  batch), risk scoring, IP reputation, Tor detection, ASN lookup, WHOIS,
+  reverse/forward DNS, MX records, domain age (single + batch), rate limit
+  and usage info.
+- Typed errors (`AuthenticationError`, `RateLimitError` with x-ratelimit
+  header values, `InvalidRequestError`, `ServerError`).
+- Zero runtime dependencies (stdlib `net/http`).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ip-api.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,120 @@
+# ip-api-io — Official Ruby client for [ip-api.io](https://ip-api.io)
+
+[![Gem Version](https://img.shields.io/gem/v/ip-api-io)](https://rubygems.org/gems/ip-api-io)
+[![test](https://github.com/ip-api-io/ipapi-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/ip-api-io/ipapi-ruby/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+The official Ruby client for the [ip-api.io](https://ip-api.io) IP intelligence
+platform. One client covers [IP geolocation](https://ip-api.io/what-is-my-ip),
+[email validation](https://ip-api.io/email-validation) and [verification](https://ip-api.io/email-verification-api)
+(syntax, MX, SMTP deliverability), [fraud detection](https://ip-api.io/fraud-detection-api)
+and [risk scoring](https://ip-api.io/risk-score),
+[VPN](https://ip-api.io/vpn-detection-api)/[proxy](https://ip-api.io/proxy-detection-api)/[Tor detection](https://ip-api.io/tor-detection),
+[disposable email detection](https://ip-api.io/disposable-email-checker), [ASN lookup](https://ip-api.io/asn-lookup),
+[WHOIS](https://ip-api.io/whois-lookup), [reverse DNS](https://ip-api.io/reverse-dns-lookup),
+[MX records](https://ip-api.io/mx-record-lookup) and [domain age](https://ip-api.io/domain-age-checker).
+
+Zero runtime dependencies — pure standard library.
+
+## Install
+
+```bash
+gem install ip-api-io
+```
+
+or in your Gemfile:
+
+```ruby
+gem "ip-api-io"
+```
+
+## Quickstart
+
+```ruby
+require "ip-api-io"
+
+client = IpApiIo::Client.new(api_key: "YOUR_API_KEY") # free key at https://ip-api.io
+
+# Where is this IP, and is it risky?
+info = client.lookup("8.8.8.8")
+puts info["location"]["country"]            # "United States"
+puts info["suspicious_factors"]["is_vpn"]   # false
+
+risk = client.risk_score("8.8.8.8")
+puts "#{risk['score']} #{risk['risk_level']}" # 0 low
+
+email = client.validate_email("user@example.com")
+puts "#{email['reachable']} #{email['disposable']}" # yes false
+```
+
+An API key is required — the API rejects keyless requests with `401`. Sign up at
+[ip-api.io](https://ip-api.io) for a free key.
+
+## Documentation
+
+Each guide documents the methods for one capability, with runnable examples and a link
+to the matching ip-api.io product page:
+
+- **[IP geolocation & bulk lookup](docs/ip-geolocation.md)** — `lookup`, `lookup_batch`
+- **[Email validation & verification](docs/email-validation.md)** — `email_info`, `validate_email`, `validate_email_batch`
+- **[Fraud detection & risk scoring](docs/fraud-risk-scoring.md)** — `risk_score`, `email_risk_score`, `ip_reputation`
+- **[VPN, proxy & Tor detection](docs/vpn-proxy-tor.md)** — `tor_check`, `suspicious_factors`
+- **[ASN & DNS lookups](docs/asn-and-dns.md)** — `asn`, `whois`, `reverse_dns`, `forward_dns`, `mx_records`
+- **[Domain age checker](docs/domain-age.md)** — `domain_age`, `domain_age_batch`
+- **[Errors, rate limits & usage](docs/error-handling.md)** — error types, `rate_limit`, `usage_summary`
+
+## Methods
+
+Every method maps to one ip-api.io endpoint and its product page:
+
+| Method | Endpoint | Product page |
+|---|---|---|
+| `lookup(ip = nil)` | `GET /api/v1/ip[/{ip}]` | [IP geolocation](https://ip-api.io/what-is-my-ip) |
+| `lookup_batch(ips)` | `POST /api/v1/ip/batch` (≤100 IPs) | [Bulk IP lookup](https://ip-api.io/bulk-ip-lookup) |
+| `email_info(email)` | `GET /api/v1/email/{email}` | [Email validation](https://ip-api.io/email-validation) |
+| `validate_email(email)` | `GET /api/v1/email/advanced/{email}` | [Advanced email validation](https://ip-api.io/advanced-email-validation) |
+| `validate_email_batch(emails)` | `POST /api/v1/email/advanced/batch` (≤100) | [Email list cleaning](https://ip-api.io/email-list-cleaning) |
+| `risk_score(ip = nil)` | `GET /api/v1/risk-score[/{ip}]` | [Risk score](https://ip-api.io/risk-score) |
+| `email_risk_score(email)` | `GET /api/v1/risk-score/email/{email}` | [Fraud detection](https://ip-api.io/fraud-detection-api) |
+| `ip_reputation(ip)` | `GET /api/v1/ip-reputation/{ip}` | [IP reputation](https://ip-api.io/ip-reputation) |
+| `tor_check(ip)` | `GET /api/v1/tor/{ip}` | [Tor detection](https://ip-api.io/tor-detection) |
+| `asn(ip)` | `GET /api/v1/asn/{ip}` | [ASN lookup](https://ip-api.io/asn-lookup) |
+| `whois(domain)` | `GET /api/v1/dns/whois/{domain}` | [WHOIS lookup](https://ip-api.io/whois-lookup) |
+| `reverse_dns(ip)` | `GET /api/v1/dns/reverse/{ip}` | [Reverse DNS](https://ip-api.io/reverse-dns-lookup) |
+| `forward_dns(hostname)` | `GET /api/v1/dns/forward/{hostname}` | — |
+| `mx_records(domain)` | `GET /api/v1/dns/mx/{domain}` | [MX record lookup](https://ip-api.io/mx-record-lookup) |
+| `domain_age(domain)` | `GET /api/v1/domain/age/{domain}` | [Domain age checker](https://ip-api.io/domain-age-checker) |
+| `domain_age_batch(domains)` | `POST /api/v1/domain/age/batch` | [Domain age checker](https://ip-api.io/domain-age-checker) |
+| `rate_limit` | `GET /api/v1/ratelimit` | — |
+| `usage_summary` | `GET /api/v1/usage/summary` | — |
+
+All methods return parsed JSON as plain Hashes.
+
+## Error handling
+
+The client raises typed errors and **never retries** — on `429`,
+`RateLimitError#reset` tells you when your quota renews:
+
+```ruby
+begin
+  client.lookup("8.8.8.8")
+rescue IpApiIo::RateLimitError => e
+  puts "limit=#{e.limit} remaining=#{e.remaining} resets_at=#{e.reset}"
+rescue IpApiIo::AuthenticationError
+  puts "invalid API key"
+end
+```
+
+See [docs/error-handling.md](docs/error-handling.md) for the full error taxonomy.
+
+## Links
+
+- Website: https://ip-api.io
+- API reference: https://ip-api.io/api-docs.html
+- OpenAPI spec: https://ip-api.io/openapi.json
+- Get a free API key: https://ip-api.io
+
+---
+
+`ip-api-io` is the official client for [ip-api.io](https://ip-api.io).
+It is not affiliated with ip-api.com or ipapi.com.

data/lib/ip-api-io.rb

@@ -0,0 +1,3 @@
+require_relative "ipapi_io/version"
+require_relative "ipapi_io/errors"
+require_relative "ipapi_io/client"

data/lib/ipapi_io/client.rb

@@ -0,0 +1,194 @@
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "errors"
+require_relative "version"
+
+module IpApiIo
+  # Client for the ip-api.io IP intelligence and email validation API.
+  #
+  #   client = IpApiIo::Client.new(api_key: "YOUR_API_KEY")
+  #   client.lookup("8.8.8.8") #=> { "ip" => "8.8.8.8", "location" => {...}, ... }
+  #
+  # An API key is required by the live API — get a free key at https://ip-api.io.
+  class Client
+    BASE_URL = "https://ip-api.io".freeze
+    MAX_BATCH_SIZE = 100
+
+    def initialize(api_key: nil, base_url: BASE_URL, timeout: 10)
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      @timeout = timeout
+    end
+
+    # -- IP intelligence ------------------------------------------------------
+
+    # Geolocation + threat intelligence for an IP (or the caller's IP when nil).
+    def lookup(ip = nil)
+      request(:get, ip ? "/api/v1/ip/#{encode(ip)}" : "/api/v1/ip")
+    end
+
+    # Look up to 100 IP addresses in a single request.
+    def lookup_batch(ips)
+      check_batch!(ips, "ips")
+      request(:post, "/api/v1/ip/batch", body: { ips: ips })
+    end
+
+    def ip_reputation(ip)
+      request(:get, "/api/v1/ip-reputation/#{encode(ip)}")
+    end
+
+    def tor_check(ip)
+      request(:get, "/api/v1/tor/#{encode(ip)}")
+    end
+
+    def asn(ip)
+      request(:get, "/api/v1/asn/#{encode(ip)}")
+    end
+
+    # -- Email validation -------------------------------------------------------
+
+    # Syntax, disposability and MX analysis of an email address.
+    def email_info(email)
+      request(:get, "/api/v1/email/#{encode(email)}")
+    end
+
+    # Advanced validation including SMTP deliverability checks.
+    def validate_email(email)
+      request(:get, "/api/v1/email/advanced/#{encode(email)}")
+    end
+
+    # Advanced-validate up to 100 email addresses in a single request.
+    def validate_email_batch(emails)
+      check_batch!(emails, "emails")
+      request(:post, "/api/v1/email/advanced/batch", body: { emails: emails })
+    end
+
+    # -- Risk scoring -----------------------------------------------------------
+
+    # Fraud risk score for an IP (or the caller's IP when nil).
+    def risk_score(ip = nil)
+      request(:get, ip ? "/api/v1/risk-score/#{encode(ip)}" : "/api/v1/risk-score")
+    end
+
+    def email_risk_score(email)
+      request(:get, "/api/v1/risk-score/email/#{encode(email)}")
+    end
+
+    # -- DNS & domains ----------------------------------------------------------
+
+    def whois(domain)
+      request(:get, "/api/v1/dns/whois/#{encode(domain)}")
+    end
+
+    def reverse_dns(ip)
+      request(:get, "/api/v1/dns/reverse/#{encode(ip)}")
+    end
+
+    def forward_dns(hostname)
+      request(:get, "/api/v1/dns/forward/#{encode(hostname)}")
+    end
+
+    def mx_records(domain)
+      request(:get, "/api/v1/dns/mx/#{encode(domain)}")
+    end
+
+    def domain_age(domain)
+      request(:get, "/api/v1/domain/age/#{encode(domain)}")
+    end
+
+    def domain_age_batch(domains)
+      raise ArgumentError, "domains must not be empty" if domains.empty?
+
+      request(:post, "/api/v1/domain/age/batch", body: { domains: domains })
+    end
+
+    # -- Account ----------------------------------------------------------------
+
+    def rate_limit
+      request(:get, "/api/v1/ratelimit")
+    end
+
+    def usage_summary
+      request(:get, "/api/v1/usage/summary")
+    end
+
+    private
+
+    def encode(value)
+      URI.encode_uri_component(value.to_s)
+    end
+
+    def check_batch!(items, name)
+      raise ArgumentError, "#{name} must not be empty" if items.empty?
+      raise ArgumentError, "#{name} must contain at most #{MAX_BATCH_SIZE} items" if items.size > MAX_BATCH_SIZE
+    end
+
+    def request(method, path, body: nil)
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(api_key: @api_key) if @api_key
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      klass = method == :post ? Net::HTTP::Post : Net::HTTP::Get
+      req = klass.new(uri)
+      req["User-Agent"] = USER_AGENT
+      req["Accept"] = "application/json"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      response = http.request(req)
+      return parse_body(response.body) if response.is_a?(Net::HTTPSuccess)
+
+      raise error_for(response)
+    end
+
+    def parse_body(raw)
+      raw.nil? || raw.empty? ? nil : JSON.parse(raw)
+    end
+
+    def error_for(response)
+      status = response.code.to_i
+      raw = response.body.to_s
+      message = begin
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? (parsed["message"] || parsed["error"]).to_s : ""
+      rescue JSON::ParserError
+        raw.strip[0, 200]
+      end
+      message = "HTTP #{status} from ip-api.io" if message.empty?
+
+      case status
+      when 401, 403
+        AuthenticationError.new(message, status_code: status, body: raw)
+      when 429
+        RateLimitError.new(
+          message,
+          body: raw,
+          limit: header_int(response, "x-ratelimit-limit"),
+          remaining: header_int(response, "x-ratelimit-remaining"),
+          reset: header_int(response, "x-ratelimit-reset")
+        )
+      when 400, 404, 422
+        InvalidRequestError.new(message, status_code: status, body: raw)
+      when 500..599
+        ServerError.new(message, status_code: status, body: raw)
+      else
+        Error.new(message, status_code: status, body: raw)
+      end
+    end
+
+    def header_int(response, name)
+      value = response[name]
+      Integer(value, 10)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+end

data/lib/ipapi_io/errors.rb

@@ -0,0 +1,34 @@
+module IpApiIo
+  # Base error for all ip-api.io client failures.
+  class Error < StandardError
+    attr_reader :status_code, :body
+
+    def initialize(message, status_code: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @body = body
+    end
+  end
+
+  # HTTP 401/403 — missing or invalid API key.
+  class AuthenticationError < Error; end
+
+  # HTTP 429 — quota exhausted. Exposes the x-ratelimit-* response headers;
+  # +reset+ is the unix timestamp when the quota renews. The client never retries.
+  class RateLimitError < Error
+    attr_reader :limit, :remaining, :reset
+
+    def initialize(message, status_code: 429, body: nil, limit: nil, remaining: nil, reset: nil)
+      super(message, status_code: status_code, body: body)
+      @limit = limit
+      @remaining = remaining
+      @reset = reset
+    end
+  end
+
+  # HTTP 400/404/422 — malformed input or unknown resource.
+  class InvalidRequestError < Error; end
+
+  # HTTP 5xx — ip-api.io server-side failure.
+  class ServerError < Error; end
+end

data/lib/ipapi_io/version.rb

@@ -0,0 +1,4 @@
+module IpApiIo
+  VERSION = "1.0.0".freeze
+  USER_AGENT = "ip-api-io-ruby/#{VERSION}".freeze
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: ip-api-io
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ip-api.io
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+description: 'Ruby client for the ip-api.io IP intelligence platform: IP geolocation,
+  email validation (syntax, MX, SMTP deliverability), fraud detection and risk scoring,
+  VPN/proxy/Tor detection, ASN lookup, WHOIS, reverse/forward DNS and domain age.
+  Zero runtime dependencies.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ip-api-io.rb
+- lib/ipapi_io/client.rb
+- lib/ipapi_io/errors.rb
+- lib/ipapi_io/version.rb
+homepage: https://ip-api.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://ip-api.io
+  documentation_uri: https://ip-api.io/docs
+  source_code_uri: https://github.com/ip-api-io/ipapi-ruby
+  changelog_uri: https://github.com/ip-api-io/ipapi-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ip-api-io/ipapi-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Official Ruby client for ip-api.io — IP geolocation, email validation, fraud
+  detection and risk scoring API
+test_files: []