masklen

Official Ruby SDK for the masklen.dev IP intelligence API.

Look up geolocation, network, privacy, and locale data for any IPv4 or IPv6 address. Zero external dependencies -- uses only Ruby stdlib.

Installation

Add to your Gemfile:

gem "masklen"

Or install directly:

gem install masklen

Quick start

require "masklen"

client = Masklen::Client.new(api_key: "your-api-key")

# 1. Look up a specific IP address
result = client.lookup("8.8.8.8")
puts result.ip                   # "8.8.8.8"
puts result.location.country     # "United States"
puts result.network.isp          # "Google LLC"
puts result.privacy.threat_level # "low"

# 2. Look up your own IP (the caller's IP as seen by the server)
self_result = client.lookup_self
puts self_result.location.city

# 3. Batch lookup (up to 1000 IPs per request)
batch = client.lookup_batch(["8.8.8.8", "1.1.1.1"])
batch.results.each do |r|
  if r.is_a?(Masklen::LookupResult)
    puts "#{r.ip} -> #{r.location&.country}"
  else
    # r is a Masklen::BatchItemError
    puts "#{r.ip} error: #{r.error_message}"
  end
end

Method signatures

# Initialise the client
client = Masklen::Client.new(
  api_key:  "your-api-key",          # required
  base_url: "https://masklen.dev"    # optional, defaults to production
)

# Single IP lookup
result = client.lookup(ip, fields: nil)

# Caller's own IP
result = client.lookup_self(fields: nil)

# Batch lookup
batch = client.lookup_batch(ips, fields: nil)

Filtering fields

All three methods accept an optional fields: array. Pass one or more of:

• "location" -- city, region, country, coordinates, timezone
• "network" -- ASN, ISP, organisation, domain
• "privacy" -- VPN, proxy, Tor, hosting, threat level
• "locale" -- currency, calling code, languages, flag

# Fetch only location and privacy data to reduce response size
result = client.lookup("8.8.8.8", fields: ["location", "privacy"])
puts result.location.city
puts result.privacy.vpn

# Omit fields entirely to receive all data
result = client.lookup("8.8.8.8")

Response types

All types are Struct subclasses with keyword arguments.

LookupResult

Field	Type
ip	String
location	Location, nil
network	Network, nil
privacy	Privacy, nil
locale	Locale, nil

Location

Field	Type
city	String, nil
region	String, nil
country	String, nil
country_code	String, nil
latitude	Float, nil
longitude	Float, nil
postal_code	String, nil
timezone	String, nil

Network

Field	Type
asn	String, nil
isp	String, nil
organization	String, nil
domain	String, nil

Privacy

Field	Type
vpn	Boolean
proxy	Boolean
tor	Boolean
hosting	Boolean
threat_level	String ("low" or "medium")

Locale

Field	Type
currency	String, nil
currency_symbol	String, nil
calling_code	String, nil
languages	Array
flag	String, nil

BatchResult

Field	Type
results	Array

BatchItemError

Field	Type
ip	String
error_code	String
error_message	String

Error handling

All API errors raise Masklen::Error, a subclass of StandardError.

begin
  result = client.lookup("8.8.8.8")
rescue Masklen::Error => e
  puts e.status_code    # HTTP status, e.g. 401
  puts e.error_code     # machine-readable code, e.g. "unauthorized"
  puts e.error_message  # human-readable message
  puts e.message        # full formatted message string
end

Network errors (timeouts, connection refused, DNS failures) are also wrapped in Masklen::Error with status_code: 0 and error_code: "network_error".

Requirements

• Ruby 3.0 or later
• No external runtime dependencies (stdlib only: net/http, uri, json)

License

MIT