IPGeolocation Ruby SDK

Overview

Official Ruby SDK for the IPGeolocation.io IP Location API.

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk . Get geolocation, company, ASN, timezone, network, hostname, abuse, user-agent, and security data from one API.

• Ruby 2.7+
• Sync client built on Net::HTTP
• Typed responses plus raw JSON and XML methods

Install

gem install ipgeolocation_sdk

Or add it to your Gemfile :

gem "ipgeolocation_sdk", "~> 2.0"

Then run:

bundle install

require "ipgeolocation_sdk"

RubyGems package: ipgeolocation_sdk Package page: https://rubygems.org/gems/ipgeolocation_sdkGitHub repository: https://github.com/IPGeolocation/ip-geolocation-ruby-sdk

Quick Start

require "ipgeolocation_sdk"

client = IpgeolocationSdk::IpGeolocationClient.new(
  api_key: ENV.fetch("IPGEO_API_KEY")
)

begin
  response = client.lookup_ip_geolocation(ip: "8.8.8.8")

  puts response.data.ip # 8.8.8.8
  puts response.data.location&.country_name # United States
  puts response.data.location&.city
  puts response.data.time_zone&.name
  puts response.metadata.credits_charged
ensure
  client.close
end

You can also pass LookupIpGeolocationRequest and BulkLookupIpGeolocationRequest objects if you want validation before the request is sent.

At a Glance

Get Your API Key

To use most SDK features, create or access your IPGeolocation account and copy an API key from your dashboard.

1. Sign up: https://app.ipgeolocation.io/signup
2. Verify your email if prompted
3. Sign in: https://app.ipgeolocation.io/login
4. Open your dashboard: https://app.ipgeolocation.io/dashboard
5. Copy an API key from the API Keys section

For server-side code, keep the API key in an environment variable or secret manager. For browser-based single lookups on paid plans, use request-origin auth instead of exposing an API key in frontend code.

Plan Behavior

Feature availability depends on your plan and request parameters.

Paid plans still need include for optional modules. fields and excludes only trim the response. They do not turn modules on or unlock paid data.

Client Configuration

The client constructor accepts either an IpGeolocationClientConfig or a hash with the same keys.

Available Methods

Request Options

Examples

The examples below assume you already have a configured client in scope:

client = IpgeolocationSdk::IpGeolocationClient.new(
  api_key: ENV.fetch("IPGEO_API_KEY")
)

response = client.lookup_ip_geolocation
puts response.data.ip

response = client.lookup_ip_geolocation(ip: "ipgeolocation.io")

puts response.data.ip
puts response.data.domain # ipgeolocation.io
puts response.data.location&.country_name

response = client.lookup_ip_geolocation(
  ip: "9.9.9.9",
  include: ["security", "abuse"]
)

puts response.data.security&.threat_score
puts response.data.abuse&.emails&.first

visitor_ua = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_2) AppleWebKit/601.3.9 (KHTML, like Gecko) Version/9.0.2 Safari/601.3.9"

response = client.lookup_ip_geolocation(
  ip: "115.240.90.163",
  include: ["user_agent"],
  headers: { "User-Agent" => visitor_ua }
)

puts response.data.user_agent&.name
puts response.data.user_agent&.operating_system&.name

response = client.lookup_ip_geolocation(
  ip: "8.8.8.8",
  include: ["security"],
  fields: ["location.country_name", "security.threat_score", "security.is_vpn"],
  excludes: ["currency"]
)

puts response.data.location&.country_name
puts response.data.security&.threat_score
puts response.data.security&.is_vpn

response = client.lookup_ip_geolocation_raw(
  ip: "8.8.8.8",
  output: IpgeolocationSdk::ResponseFormat::XML
)

puts response.data

response = client.bulk_lookup_ip_geolocation(
  ips: ["8.8.8.8", "invalid-ip", "1.1.1.1"],
  include: ["security"]
)

response.data.each do |result|
  if result.success?
    puts result.data.ip
    puts result.data.security&.threat_score
    next
  end

  puts result.error.message
end

Response Metadata

Each method returns an ApiResponse with data and metadata .

metadata includes:

Helper methods:

metadata = response.metadata

puts metadata.status_code
puts metadata.duration_ms
puts metadata.header_values("X-Credits-Charged").inspect
puts metadata.first_header_value("Content-Type")

JSON Helpers

Use these helpers to turn SDK objects into JSON:

puts IpgeolocationSdk.to_json(response.data)
puts IpgeolocationSdk.to_pretty_json(response.data)
puts IpgeolocationSdk.to_pretty_json(response.data, :full)

Compact mode omits nil fields. Full mode keeps them.

Errors

The SDK raises these exception classes:

• IpgeolocationSdk::ValidationError
• IpgeolocationSdk::SerializationError
• IpgeolocationSdk::TransportError
• IpgeolocationSdk::RequestTimeoutError
• IpgeolocationSdk::ApiError
• IpgeolocationSdk::BadRequestError
• IpgeolocationSdk::UnauthorizedError
• IpgeolocationSdk::NotFoundError
• IpgeolocationSdk::MethodNotAllowedError
• IpgeolocationSdk::PayloadTooLargeError
• IpgeolocationSdk::UnsupportedMediaTypeError
• IpgeolocationSdk::LockedError
• IpgeolocationSdk::RateLimitError
• IpgeolocationSdk::ClientClosedRequestError
• IpgeolocationSdk::ServerError

Example:

begin
  client.lookup_ip_geolocation(ip: "8.8.8.8")
rescue IpgeolocationSdk::ApiError => error
  puts error.status_code
  puts error.api_message
  puts error.message
end

Troubleshooting

• bulk lookup requires api_key in client config Bulk lookup does not support request-origin auth on its own.
• single lookup requires api_key or request_origin in client config Set at least one authentication option before calling the single lookup methods.
• XML output is not supported by typed methods Use lookup_ip_geolocation_raw or bulk_lookup_ip_geolocation_raw for XML output.
• client is closed Create a new client after calling close .
• TransportError or RequestTimeoutError Increase connect_timeout or read_timeout , or add your own retry logic.

Frequently Asked Questions

Links

• API docs: https://ipgeolocation.io/documentation/ip-location-api.html
• Dashboard: https://app.ipgeolocation.io/dashboard
• Pricing: https://ipgeolocation.io/pricing.html
• RubyGems package: https://rubygems.org/gems/ipgeolocation_sdk
• GitHub repo: https://github.com/IPGeolocation/ip-geolocation-ruby-sdk