IP2Location.io Ruby SDK — IP Geolocation, Domain WHOIS & Hosted Domain Lookup

IP2Location.io Ruby SDK (ip2location_io_ruby) is a Ruby gem for retrieving IPv4 and IPv6 geolocation, network and IP intelligence data through the IP2Location.io API. It also includes domain WHOIS lookup, domain/Punycode helpers and hosted domain lookup. Use its Ruby methods to integrate IP and domain information into scripts or applications without constructing API requests manually.

Quick links: Get an API key · Developer documentation · Ruby API reference · RubyGems package

Features

• IPv4 and IPv6 geolocation: Retrieve country, region, district, city, coordinates, ZIP/postal code and time zone information.
• Network and ASN information: Access available ASN, AS name, ISP, associated domain, connection speed and usage type data.
• Localization information: Request translated continent, country, region and city names when supported by your API plan (Plus and Security plans).
• Proxy and security signals: Inspect available proxy, VPN, Tor, data center, crawler and other security-related indicators, including fraud score where provided.
• Additional IP intelligence: Retrieve available country metadata, mobile network details (MCC/MNC), elevation, weather information and advertising categories.
• Domain WHOIS lookup: Retrieve available domain registration details, dates, registrar, nameservers and contact information.
• Internationalized domain utilities: Convert Unicode domain names to and from Punycode; extract domain names and extensions.
• Hosted domain lookup: Get a list of domain names hosted on an IPv4 or IPv6 address, including optional page selection.

Plan availability: The response fields depend on the API plan and queried address. Some properties may be absent or unavailable. Refer to the API plans and Ruby API field reference.

SDK classes

The Ruby SDK exposes the following configuration and API classes:

Class	Description
IP2LocationIORuby::Configuration	Configures the API key using Configuration.api_key.
IP2LocationIORuby::Api::IPGeolocation	Retrieves geolocation, network and available security data for an IPv4 or IPv6 address.
IP2LocationIORuby::Api::DomainWhois	Retrieves WHOIS information and provides domain/Punycode helper methods.
IP2LocationIORuby::Api::HostedDomain	Retrieves domains hosted on an IP address with an optional page argument.

WHOIS documentation note: The Ruby API reference says this DomainWhois class is no longer maintained and points to the IP2WHOIS Ruby SDK. However, that other repository says it is no longer maintained and recommends this IP2Location.io Ruby SDK instead. These notices conflict; verify support status before choosing a WHOIS library. The examples below retain the documented methods in this SDK.

API access and query limits

IP2Location.io provides keyless geolocation requests through its REST API and a Free plan with an API key:

API service	Keyless (no API key)	Free plan (with API key)
IP Geolocation API	1,000 queries/day	50,000 queries/month
Domain WHOIS API	—	500 queries/month
Hosted Domain API	—	50 queries/month

• Keyless access: Direct IP Geolocation REST API requests can be made without registration. The daily limit resets at 00:00 UTC. The Ruby SDK examples below use an API key, as required by its documented configuration.
• Free plan: Obtain an API key to use the applicable monthly quotas.
• Attribution: Keyless and Free-plan offerings require attribution; consult the pricing page for current terms.
• Paid plans: See the pricing page for additional features, quotas and current prices.

For authentication and rate-limit details, see the IP Geolocation API documentation.

Requirements

• Ruby and RubyGems installed. The published gem does not specify a meaningful minimum Ruby version; use a currently supported Ruby release for development.
• Network access to the IP2Location.io API services.
• An IP2Location.io API key (free signup available) for the SDK examples.
• The ip2location_io_ruby gem. It declares simpleidn ~> 0.2 as a runtime dependency, normally installed automatically by RubyGems.

Installation

Install the Ruby SDK using the command shown in the official quickstart:

gem install ip2location_io_ruby

For an existing Bundler project, add this gem to your Gemfile and run bundle install:

gem 'ip2location_io_ruby'

Set your API key as an environment variable instead of putting it directly in your Ruby source code:

Linux / macOS terminal:

export IP2LOCATION_API_KEY='YOUR_API_KEY'

Windows Command Prompt:

set IP2LOCATION_API_KEY=YOUR_API_KEY

The Ruby SDK expects the key to be assigned through IP2LocationIORuby::Configuration.api_key in your program. The examples below use ENV.fetch to read the environment variable and pass it to that setting.

Quickstart: IP geolocation lookup

Create a file named lookup.rb:

require 'ip2location_io_ruby'

IP2LocationIORuby::Configuration.api_key = ENV.fetch('IP2LOCATION_API_KEY')

result = IP2LocationIORuby::Api::IPGeolocation.lookup('8.8.8.8')
puts result.body

Run the script:

ruby lookup.rb

This follows the official SDK's Configuration.api_key and IPGeolocation.lookup interface. The method returns an HTTP response object; .body contains the JSON response. Returned fields depend on your plan and the IP address. See the geolocation field reference.

More usage examples

The examples below assume the Ruby gem has been loaded and the API key configured as in the quickstart:

require 'ip2location_io_ruby'
IP2LocationIORuby::Configuration.api_key = ENV.fetch('IP2LOCATION_API_KEY')

Request translated location names

Pass the optional ISO 639-1 language code as the second argument to lookup. Location-name translations are available on Plus and Security plans.

result = IP2LocationIORuby::Api::IPGeolocation.lookup('8.8.8.8', 'es')
puts result.body

Inspect ASN and network information

The API returns JSON text in the response body. Parse it with Ruby's built-in json library to access the documented fields:

require 'json'

result = IP2LocationIORuby::Api::IPGeolocation.lookup('8.8.8.8')
data = JSON.parse(result.body)

puts "ASN: #{data['asn'] || 'N/A'}"
puts "AS name: #{data['as'] || 'N/A'}"
puts "ISP: #{data['isp'] || 'N/A'}"

The isp field and advanced network fields are available only when included in the applicable API response.

Inspect available proxy indicators

Proxy and security fields depend on the account plan and the queried IP. Check for the nested proxy object before accessing its indicators:

require 'json'

result = IP2LocationIORuby::Api::IPGeolocation.lookup('8.8.8.8')
data = JSON.parse(result.body)

puts "Proxy: #{data['is_proxy'].inspect}" if data.key?('is_proxy')

if data['proxy'].is_a?(Hash)
  puts "VPN: #{data['proxy']['is_vpn'].inspect}"
  puts "Tor: #{data['proxy']['is_tor'].inspect}"
else
  puts 'Detailed proxy indicators are unavailable for this response.'
end

Use these indicators as supporting context rather than as the sole basis for a security or fraud decision.

Look up domain WHOIS information

The Ruby SDK supports domain WHOIS lookup using the following method:

result = IP2LocationIORuby::Api::DomainWhois.lookup('example.com')
puts result.body

WHOIS details can include registration dates, registrar details and nameservers. Some contact records may be redacted or unavailable. The two Ruby repositories contain conflicting maintenance notices; check their current status before choosing one for new development.

Use domain and Punycode utilities

The official quickstart documents four helper methods:

whois = IP2LocationIORuby::Api::DomainWhois

puts whois.get_punycode('täst.de')
puts whois.get_normal_text('xn--tst-qla.de')
puts whois.get_domain_name('https://www.example.com/exe')
puts whois.get_domain_extension('example.com')

These helper methods do not require an IP geolocation lookup. The gem declares a simpleidn dependency for internationalized-domain processing.

Find domains hosted on an IP address

The documented HostedDomain.lookup method accepts an IP address and an optional page number (default: page 1):

result = IP2LocationIORuby::Api::HostedDomain.lookup('8.8.8.8')
puts result.body

To request another page, pass its number as the second argument:

result = IP2LocationIORuby::Api::HostedDomain.lookup('8.8.8.8', 2)
puts result.body

Hosted-domain responses may include total_domains, page, per_page, total_pages and domains. Check the returned pagination metadata before requesting additional pages.

Version caveat: The current repository source for HostedDomain.lookup appears to concatenate the page parameter and the subsequent source parameter without a separating &. If pagination does not work as expected, check the SDK's latest source or open an issue in the Ruby SDK repository. The method signature and page argument above follow the official API reference.

Common use cases

• Website localization: Use approximate IP location to suggest regional content, language or currency.
• Application analytics: Enrich Ruby application events or logs with country, city and ASN information.
• Network research: Investigate available ASN, AS name, ISP and hosted-domain context for an IP address.
• Security review: Consider available proxy, VPN and Tor indicators alongside other signals in a broader review.
• Domain research: Retrieve WHOIS information and use domain/Punycode utilities, while checking the libraries’ conflicting maintenance notices before new integrations.

Documentation and support

• Ruby SDK quickstart and examples
• Ruby SDK API reference and response fields
• Official GitHub repository
• Official GitHub example.rb
• RubyGems package
• IP2WHOIS Ruby SDK (check maintenance notice)
• IP2Location.io API plans and query limits
• IP Geolocation API authentication and rate limits
• Report a Ruby SDK issue or request a feature
• API and account support

License

Licensed under the MIT License. See LICENSE.txt.