IpApi

The IpApi gem provides a Ruby interface to the IP-API.com geolocation API, enabling IP address and domain lookups to retrieve location, network, and connection information.

require 'ip_api'

response = IpApi.query( '8.8.8.8' )
if response.success?
  result = response.result
  puts "#{ result.city }, #{ result.country }"  # => "Ashburn, United States"
  puts result.isp                                # => "Google LLC"
  puts result.coordinates                        # => [39.03, -77.5]
end

Installation
Command Line
Quick Start
Free vs Pro
Options
- Fields
- Language
Response
- Location Fields
- Network Fields
- Connection Fields
- Helper Methods
Error Handling
Connections
License

Installation

Add this line to your application's Gemfile:

gem 'ipapi-rb'

Then execute:

bundle install

Or install it directly:

gem install ipapi-rb

Command Line

The gem includes an ipapi command for quick lookups from the terminal:

ipapi 8.8.8.8
ipapi google.com
ipapi                           # Look up your own IP
ipapi -f country,city 8.8.8.8   # Specific fields only
ipapi -l de 8.8.8.8             # German localization
ipapi -j 8.8.8.8                # Raw JSON output

Set your Pro API key via environment variable for HTTPS and unlimited requests:

export IPAPI_API_KEY=your_api_key

Quick Start

The simplest way to use the gem is through the module-level convenience method:

require 'ip_api'

# Query an IP address
response = IpApi.query( '8.8.8.8' )
if response.success?
  result = response.result
  puts result.country       # => "United States"
  puts result.city          # => "Ashburn"
  puts result.isp           # => "Google LLC"
  puts result.hosting?      # => true
end

# Query a domain
response = IpApi.query( 'google.com' )

# Query your own IP (no argument)
response = IpApi.query

For more control, instantiate request objects directly:

request = IpApi::QueryRequest.new( api_key: ENV[ 'IPAPI_API_KEY' ] )

options = IpApi::QueryOptions.build do
  fields [ :country, :city, :isp, :proxy, :hosting ]
  lang :de
end

response = request.submit( '8.8.8.8', options )

Free vs Pro

The gem automatically selects the appropriate endpoint based on whether an API key is configured:

Feature	Free	Pro
Endpoint	`http://ip-api.com`	`https://pro.ip-api.com`
SSL/HTTPS	No	Yes
Rate Limit	45 requests/minute	Unlimited
Commercial Use	No	Yes

# Free (no API key)
response = IpApi.query( '8.8.8.8' )

# Pro (with API key)
IpApi.api_key ENV[ 'IPAPI_API_KEY' ]
response = IpApi.query( '8.8.8.8' )

# Or pass directly to request
request = IpApi::QueryRequest.new( api_key: 'your-key' )
response = request.submit( '8.8.8.8' )

Options

Fields

Control which fields are returned to reduce bandwidth:

options = IpApi::QueryOptions.build do
  fields [ :status, :country, :city, :lat, :lon ]
end

response = IpApi.query( '8.8.8.8', options )

Available fields (use snake_case in Ruby):

Field	Description
`:status`	Request status (`success` or `fail`)
`:message`	Error message (when status is `fail`)
`:query`	IP address used for the query
`:continent`	Continent name
`:continent_code`	Two-letter continent code
`:country`	Country name
`:country_code`	ISO 3166-1 alpha-2 country code
`:region`	Region/state short code
`:region_name`	Region/state full name
`:city`	City name
`:district`	District (subdivision of city)
`:zip`	Zip/postal code
`:lat`	Latitude
`:lon`	Longitude
`:timezone`	Timezone identifier
`:offset`	UTC offset in seconds
`:currency`	National currency code
`:isp`	ISP name
`:org`	Organization name
`:as`	AS number and organization
`:as_name`	AS name
`:reverse`	Reverse DNS (can delay response)
`:mobile`	Mobile connection flag
`:proxy`	Proxy/VPN/Tor flag
`:hosting`	Hosting/datacenter flag

Language

Localize the country, region_name, and city fields:

options = IpApi::QueryOptions.build do
  lang :de  # German
end

response = IpApi.query( '8.8.8.8', options )
puts response.result.country  # => "Vereinigte Staaten"

Supported languages: :en, :de, :es, :fr, :ja, :ru, :'pt-BR', :'zh-CN'

Response

Location Fields

result = response.result

result.continent        # => "North America"
result.continent_code   # => "NA"
result.country          # => "United States"
result.country_code     # => "US"
result.region           # => "VA"
result.region_name      # => "Virginia"
result.city             # => "Ashburn"
result.district         # => nil
result.zip              # => "20149"
result.lat              # => 39.03
result.lon              # => -77.5
result.timezone         # => "America/New_York"
result.offset           # => -18000
result.currency         # => "USD"

Network Fields

result.isp              # => "Google LLC"
result.org              # => "Google Public DNS"
result.as_number        # => "AS15169 Google LLC"
result.as_name          # => "GOOGLE"
result.reverse          # => "dns.google"

Connection Fields

result.mobile           # => false
result.proxy            # => false
result.hosting          # => true

Helper Methods

result.success?         # => true (status == 'success')
result.failed?          # => false (status == 'fail')

result.mobile?          # => false
result.proxy?           # => false
result.hosting?         # => true

result.coordinates      # => [39.03, -77.5]

Error Handling

The API returns errors in two ways:

HTTP errors (rate limiting):

response = IpApi.query( '8.8.8.8' )

unless response.success?
  error = response.result
  puts error.error_type         # => :rate_limit_error
  puts error.error_description  # => "The rate limit has been exceeded..."
end

API errors (invalid query, private IP):

response = IpApi.query( '192.168.1.1' )

if response.success?
  result = response.result
  if result.failed?
    puts result.message  # => "private range"
  end
end

Common API error messages:

Message	Description
`private range`	IP is in a private network range
`reserved range`	IP is in a reserved range
`invalid query`	Invalid IP or domain

Connections

The gem uses Faraday for HTTP requests. To customize the connection:

connection = Faraday.new do | faraday |
  faraday.response :logger
  faraday.adapter :net_http
end

IpApi.connection connection

Or pass it directly to a request:

request = IpApi::QueryRequest.new(
  api_key: ENV[ 'IPAPI_API_KEY' ],
  connection: connection
)

License

The gem is available as open source under the terms of the MIT License.

ipapi-rb

Development

Runtime