ip-api-io — Official Ruby client for ip-api.io

The official Ruby client for the ip-api.io IP intelligence platform. One client covers IP geolocation, email validation and verification (syntax, MX, SMTP deliverability), fraud detection and risk scoring, VPN/proxy/Tor detection, disposable email detection, ASN lookup, WHOIS, reverse DNS, MX records and domain age.

Zero runtime dependencies — pure standard library.

Install

gem install ip-api-io

or in your Gemfile:

gem "ip-api-io"

Quickstart

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 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 — lookup, lookup_batch
Email validation & verification — email_info, validate_email, validate_email_batch
Fraud detection & risk scoring — risk_score, email_risk_score, ip_reputation
VPN, proxy & Tor detection — tor_check, suspicious_factors
ASN & DNS lookups — asn, whois, reverse_dns, forward_dns, mx_records
Domain age checker — domain_age, domain_age_batch
Errors, rate limits & usage — 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
`lookup_batch(ips)`	`POST /api/v1/ip/batch` (≤100 IPs)	Bulk IP lookup
`email_info(email)`	`GET /api/v1/email/{email}`	Email validation
`validate_email(email)`	`GET /api/v1/email/advanced/{email}`	Advanced email validation
`validate_email_batch(emails)`	`POST /api/v1/email/advanced/batch` (≤100)	Email list cleaning
`risk_score(ip = nil)`	`GET /api/v1/risk-score[/{ip}]`	Risk score
`email_risk_score(email)`	`GET /api/v1/risk-score/email/{email}`	Fraud detection
`ip_reputation(ip)`	`GET /api/v1/ip-reputation/{ip}`	IP reputation
`tor_check(ip)`	`GET /api/v1/tor/{ip}`	Tor detection
`asn(ip)`	`GET /api/v1/asn/{ip}`	ASN lookup
`whois(domain)`	`GET /api/v1/dns/whois/{domain}`	WHOIS lookup
`reverse_dns(ip)`	`GET /api/v1/dns/reverse/{ip}`	Reverse DNS
`forward_dns(hostname)`	`GET /api/v1/dns/forward/{hostname}`	—
`mx_records(domain)`	`GET /api/v1/dns/mx/{domain}`	MX record lookup
`domain_age(domain)`	`GET /api/v1/domain/age/{domain}`	Domain age checker
`domain_age_batch(domains)`	`POST /api/v1/domain/age/batch`	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:

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 for the full error taxonomy.

ip-api-io