IPGeolocation.io Ruby SDK

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

Look up IPv4, IPv6, and domains with /v3/ipgeo and /v3/ipgeo-bulk. Get geolocation, company, ASN, time zone, 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
• Quick Start
• At a Glance
• Get Your API Key
• Authentication
• Plan Behavior
• Client Configuration
• Available Methods
• Request Options
• Examples
• Response Metadata
• JSON Helpers
• Errors
• Troubleshooting
• Frequently Asked Questions
• Links

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_sdk
GitHub repository: https://github.com/IPGeolocation/ip-geolocation-ruby-sdk

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.

To use most SDK features, create or access your IPGeolocation.io 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

Keep the API key in an environment variable or secret manager.

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

The API key is sent as the apiKey query parameter, so avoid logging full request URLs.

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.

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

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

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

Omit ip to look up the public IP of the machine making the request.

response = client.lookup_ip_geolocation
puts response.data.ip

Domain lookup is a paid-plan feature.

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

To parse a visitor user-agent string, pass include: ["user_agent"] and send the visitor string in the request User-Agent header.

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

Bulk lookup is a paid-plan feature and always requires api_key.

Each bulk result is either a success or an error.

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

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")

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. When serializing a client configuration, both modes replace its API key with [REDACTED]. The original key remains available through config.api_key and is used for authentication.

If a request error includes your configured API key, the SDK replaces it with [REDACTED]. This also applies to errors in typed bulk results. SDK error types and HTTP status codes stay the same. Some error details may be shortened to keep the key hidden.

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

• Missing API key Set api_key in the client configuration before making a lookup.
• 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.

• 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