Including the Library
This library is primary intended to be installed and used as a Gem. However, you can even download the package from the source code repository and vendor the folder in your application.
Regardless the way you choose to install the library, the very first step is to require the
lib/whois.rb file in your code. This is usually accomplished with the following Ruby statement (notice you don’t need to append the
# Example: Require RubyGems, then require Whois require 'rubygems' require 'whois' # Now you can use the library
Depending the Ruby version and implementation, you might not need to require RubyGems. For instance, Ruby >= 1.9 already comes with RubyGems and the following code should simply works.
# Example: Directly require Whois require 'whois' # Now you can use the library
In our examples we will assume that your code properly includes the
In order to run a WHOIS query, you first need to create a
Whois::Client. The client is responsible for guessing the appropriate
Whois::Server for your request, prepare the request, execute the query through the
Whois::Server adapter and return the
In practice, this is the most simple
Whois query you can run.
# Example: Most simple Whois query # Create a Whois::Client c = Whois::Client.new # Perform the query for the domain google.com # and store the response in the 'a' variable r = c.query("google.com")
The library offers different levels of access and customization, including some convenient shortcuts.
# Example: Advanced Whois query with custom timeout c = Whois::Client.new(:timeout => 20) r = c.query("google.com")
More details about the
Whois technical architecture are available in the architecture overview section.
Performing a WHOIS Query
This is the simplest way to send a WHOIS request is using the
c = Whois::Client.new c.query("google.com") # => # The method returns a `Whois::Record` instance which essentially looks and behaves like a `String` but it's way more powerful than a string. You can print, compare and modify it exactly as a string. c = Whois::Client.new r = c.query("google.com") puts r # the full whois record response # ... # ... `Whois` provides the ability to get WHOIS information for several [objects](/manual/usage/#usage-objects), including **TLDs**, **domain names**, **IPv4** and **IPv6** IP addresses. The client is smart enough to guess the best WHOIS server according to given query, send the request and return the response. c = Whois::Client.new # Domain WHOIS c.query("google.com") # => #<Whois::Record ...> # IPv4 Whois c.query("126.96.36.199") # => #<Whois::Record ...> The query method is stateless. For this reason, you can safely re-use the same client instance for multiple queries. w = Whois::Client.new w.query("google.com") w.query("188.8.131.52") Did I mention you can even use blocks? Whois::Client.new do |w| w.query("google.com") w.query("184.108.40.206") end ### Configuring the Client The standard `Whois::Client` works fine for most of the cases but if you want more control over the request, you can access the underlying `Whois::Client` object and use it directly. # Use a Whois::Client c = Whois::Client.new c.query("google.com") # Use a Whois::Client # passing a custom timeout value c = Whois::Client.new(:timeout => 30) c.query("google.com") h3. Shortcuts The `Whois` module provides some convenient shortcuts. One of these is the `Whois.query` method. It creates a new client and calls the `#query` method on it. The following two statements are equivalent: # WHOIS request with an explicit Whois::Client c = Whois::Client.new c.query("google.com") # WHOIS request with an implicit Whois::Client c = Whois.query("google.com") Read the [`Whois::Client` shortcuts](/manual/client/#client-shortcuts) section to learn more about all available shortcuts. ## Consuming the Record A WHOIS query returns a `Whois::Record` instance and this is just the beginning of the story. `Whois::Record` is a super powerful object. It encapsulates the full WHOIS record and it provides you the ability to parse the WHOIS response with a full object oriented notation. r = Whois.whois("google.it") # => #<Whois::Record ...> r.available? # => false r.registered? # => true r.created_on # => Fri Dec 10 00:00:00 +0100 1999 t = r.technical # => #<Whois::Record::Contact ...> t.id # => "TS7016-ITNIC" t.name # => "Technical Services" r.nameservers.each do |nameserver| puts nameserver end This feature is made possible by the `Whois::Record::Parser`. Unfortunately, due to the lack of a global standard, each WHOIS server requires a specific parser. For this reason, the library doesn't currently support all existing WHOIS servers. If you create a new parser, please consider releasing it to the public so that it can be included in a next version. ## Supported Objects The current version of `Whois` supports the following objects: - IPv4 - IPv6 - TLD - Domain names You don't need to specify the object type. The library is smart enough to detect the query type and forward the request to the appropriate WHOIS server. # Supported Objects r = Whois.query("google.com") # Domain name r = Whois.query(".com") # TLD r = Whois.query("220.127.116.11") # IPv4 r = Whois.query("2a00:1450:8006::63") # IPv6