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

Table of Contents

• 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

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_sdk
GitHub 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

Item	Value
Gem	ipgeolocation_sdk
Module	IpgeolocationSdk
Supported Endpoints	/v3/ipgeo, /v3/ipgeo-bulk
Supported Inputs	IPv4, IPv6, domain
Main Data Returned	Geolocation, company, ASN, time zone, network, hostname, abuse, user-agent, currency, security
Authentication	API key
Response Formats	Structured JSON, raw JSON, raw XML
Bulk Limit	Up to 50,000 IPs or domains per request
Transport	Net::HTTP

Get Your API Key

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.

Authentication

API Key

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.

Plan Behavior

Feature availability depends on your plan and request parameters.

Capability	Free	Paid
Single IPv4 and IPv6 lookup	Supported	Supported
Domain lookup	Not supported	Supported
Bulk lookup	Not supported	Supported
Non-English lang	Not supported	Supported
Optional modules via include	Not supported	Supported
include: ["*"]	Base response only	All plan-available modules

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

Field	Type	Default	Notes
api_key	String	unset	Your IPGeolocation.io API key.
base_url	String	https://api.ipgeolocation.io	Override the API base URL.
connect_timeout	Numeric	10.0	Time to open the connection, in seconds.
read_timeout	Numeric	30.0	Time to wait while reading the response body, in seconds.

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

Available Methods

Method	Returns	Notes
lookup_ip_geolocation(request = nil)	ApiResponse with typed data	Single lookup. Typed JSON response.
lookup_ip_geolocation_raw(request = nil)	ApiResponse with String data	Single lookup. Raw JSON or XML string.
bulk_lookup_ip_geolocation(request)	ApiResponse with bulk result array	Bulk lookup. Typed JSON response.
bulk_lookup_ip_geolocation_raw(request)	ApiResponse with String data	Bulk lookup. Raw JSON or XML string.
close	nil	Closes the client. Do not reuse the client after this.

Note

Typed methods support JSON only. Use the raw methods when you need XML output.

Request Options

Field	Applies To	Notes
ip	Single lookup	IPv4, IPv6, or domain. Omit it for caller IP lookup.
ips	Bulk lookup	Array of 1 to 50,000 IPs or domains.
lang	Single and bulk	One of en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar (Arabic).
include	Single and bulk	Array of module names such as security, abuse, user_agent, hostname, liveHostname, hostnameFallbackLive, geo_accuracy, dma_code, or *.
fields	Single and bulk	Array of field paths to keep, for example ["location.country_name", "security.threat_score"].
excludes	Single and bulk	Array of field paths to remove from the response.
user_agent	Single and bulk	Overrides the outbound User-Agent header.
headers	Single and bulk	Extra request headers. Use a hash where each value is a string or an array of strings.
output	Single and bulk	"json" or "xml". Typed methods require JSON.

Examples

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

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

Caller IP

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

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

Security and Abuse

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

User-Agent Parsing

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

Note

The user_agent request field overrides the SDK's default outbound User-Agent header. It takes precedence over headers["User-Agent"].

Filtered Response

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

Raw XML

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

puts response.data

Bulk Lookup

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

Response Metadata

Each method returns an ApiResponse with data and metadata.

metadata includes:

Field	Meaning
credits_charged	Credits charged for the request when the API returns that header
successful_records	Number of successful bulk records when the API returns that header
status_code	HTTP status code
duration_ms	Client-side request time in milliseconds
raw_headers	Response headers as Hash<String, Array<String>>

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. 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.

Errors

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

Troubleshooting

• 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.

Frequently Asked Questions

Can I pass a plain hash instead of a request object?

Yes. All client methods accept either the typed request object or a plain hash with the same keys.

How do I look up my own public IP?

Call lookup_ip_geolocation with no ip value.

How do I get XML?

Use the raw methods with output: IpgeolocationSdk::ResponseFormat::XML.

How do I read bulk errors?

Check result.success?. Success items use result.data. Error items use result.error.message.

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