Ruby SDK

Overview

The IPFly Ruby SDK wraps the IPFly API in a single dependency-free file. It relies only on the standard library (net/http, json, ipaddr, monitor, thread) and handles caching, retries, rate limiting, and thread-safe request de-duplication so your integration code can stay focused on what to do with the response.

Where This SDK Belongs

If you need geolocation results in a browser-facing app, put this SDK behind your own backend endpoint and call that endpoint from the client (see the Sinatra/Rails proxy example below), or use the IPFly JavaScript SDK with a domain-restricted token for prototyping.

Installation

No gem is published — copy ipfly_sdk.rb into your project.

# Drop ipfly_sdk.rb directly into your source tree, e.g.:
cp ipfly_sdk.rb lib/ipfly_sdk.rb

curl -O https://ipfly.world/libs/ruby-sdk/ipfly_sdk.rb
# or
wget https://ipfly.world/libs/ruby-sdk/ipfly_sdk.rb

require_relative 'ipfly_sdk'

client = IPFly::Client.new('YOUR_TOKEN')

Requirements

Ruby 2.7+ (uses keyword arguments and Struct with a block; no newer syntax required). No gems — just the Ruby standard library. Works on MRI, JRuby, and TruffleRuby.

Quick Start

Create a client once, then call lookup wherever you need geolocation data.

require_relative 'ipfly_sdk'

client = IPFly::Client.new(
  'YOUR_TOKEN',
  include: 'security' # optional: request the security/ASN field set on every call
)

# Look up a specific IP
data = client.lookup('8.8.8.8')
puts "#{data['city']} #{data['country_name']} VPN: #{data['security']['is_vpn']}"

# Look up the caller's own IP (omit the ip argument)
me = client.lookup_self
puts "You appear to be in #{me['city']}"

# Handle errors explicitly
begin
  client.lookup('not-an-ip')
rescue IPFly::Error => e
  puts "#{e.code}: #{e.message}"
end

Client Options

All options are keyword arguments to IPFly::Client.new(token, **options).

Cache Options

Passed as the cache hash, e.g. IPFly::Client.new(token, cache: { storage: :file, ttl: 3600 }).

lookup & lookup_self

#lookup(ip = nil, include: nil, skip_cache: false, timeout: nil) looks up a single IP. Pass nil (or omit) to geolocate the caller — or use the #lookup_self(**kwargs) shorthand.

client.lookup(
  '1.1.1.1',
  include: 'security', # overrides the client-level `include` for this call only
  skip_cache: true,     # force a fresh network request, bypassing the cache
  timeout: 3.0            # override the client's default timeout for this call
)

Returns the parsed JSON response as a Hash (see Response Shape). Raises IPFly::Error on failure (see Error Handling).

batch_lookup

#batch_lookup(ips, concurrency: nil, **kwargs) looks up an array of IPs using a bounded pool of worker threads (concurrency overrides the client default). This call never raises for an individual IP failure — it returns an array of IPFly::BatchResult in the same order as ips.

results = client.batch_lookup(['8.8.8.8', '1.1.1.1', 'not-an-ip'])
results.each do |r|
  if r.ok?
    puts "#{r.ip} -> #{r.data['city']}"
  else
    puts "#{r.ip} failed: #{r.error.code}"
  end
end

BatchResult is a Struct: ip, ok (also available as #ok?), data, error.

Cache Controls

IPFly.valid_ip?()

A module-level helper that validates an IPv4 or IPv6 string without making a request.

IPFly.valid_ip?('8.8.8.8')               # true
IPFly.valid_ip?('2001:4860:4860::8888')  # true
IPFly.valid_ip?('not-an-ip')             # false

Response Shape

Successful lookups return the same JSON structure the IPFly API returns, unchanged, as a Ruby Hash with string keys (not symbols) — see the full field reference in the API docs. Shape depends on your plan and the include value requested.

{
  "ip" => "8.8.8.8",
  "hostname" => "dns.google",
  "country_name" => "United States",
  "city" => "Mountain View",
  "latitude" => "37.4056",
  "longitude" => "-122.0775",
  "time_zone" => { "name" => "America/New_York", "..." => "..." },
  "asn" => { "asn" => "AS15169", "name" => "Google LLC", "..." => "..." },
  "security" => { "is_vpn" => false, "is_tor" => false, "..." => "..." }
}

Error Handling

All failures raise IPFly::Error, a StandardError subclass carrying #message, #status, #code, and #cause.

client = IPFly::Client.new('YOUR_TOKEN')

begin
  client.lookup('8.8.8.8')
rescue IPFly::Error => e
  if e.code == 'TIMEOUT'
    # retry later, log, fall back to a default
  elsif e.status == 401
    # token is invalid — surface a config error, don't retry
  end
  puts e.message
end

Performance Notes

Extending the Cache

For a multi-process deployment (Puma/Unicorn workers, multiple dynos), implement the same interface as MemoryStore/FileStore (get, set, delete, keys, size, clear) over whatever shared store you already use — or simplest, wrap Rails.cache:

class RailsCacheStore
  def initialize(prefix: 'ipfly:')
    @prefix = prefix
  end

  def get(key)
    Rails.cache.read("#{@prefix}#{key}")
  end

  def set(key, value)
    Rails.cache.write("#{@prefix}#{key}", value)
  end

  def delete(key)
    Rails.cache.delete("#{@prefix}#{key}")
  end

  # Rails.cache doesn't support key enumeration by default, so LRU
  # eviction and #size are left to your cache store's own expiry policy.
  def keys
    []
  end

  def size
    0
  end

  def clear
    nil
  end
end

Examples

Three common integration patterns: enriching a CSV of visitor IPs in bulk, a Sinatra proxy, and a Rails controller.

require 'csv'
require_relative 'ipfly_sdk'

client = IPFly::Client.new(ENV.fetch('IPFLY_TOKEN'), cache: { storage: :file, path: 'geo_cache.json' })

ips = CSV.read('visitors.csv', headers: true).map { |row| row['ip'] }

client.batch_lookup(ips, concurrency: 8).each do |result|
  if result.ok?
    puts "#{result.ip} -> #{result.data['country_name']}"
  else
    puts "#{result.ip} -> error: #{result.error.code}"
  end
end

require 'sinatra'
require_relative 'ipfly_sdk'

client = IPFly::Client.new(ENV.fetch('IPFLY_TOKEN'))

get '/api/geo' do
  content_type :json
  ip = params['ip'] || request.ip
  begin
    client.lookup(ip, include: 'security').to_json
  rescue IPFly::Error => e
    status e.status || 502
    { error: e.code, message: e.message }.to_json
  end
end

class GeoController < ApplicationController
  def show
    client = Rails.application.config.x.ipfly_client # memoize this in an initializer
    data = client.lookup(params[:ip] || request.remote_ip, include: 'security')
    render json: data
  rescue IPFly::Error => e
    render json: { error: e.code, message: e.message }, status: e.status || 502
  end
end

Requirements

Ruby 2.7 or later (uses keyword arguments and Struct with a block; no newer syntax required). No gems — just the standard library. Works on MRI, JRuby, and TruffleRuby with no native extensions.

License

MIT — use it, fork it, ship it.