BigDataCloud Ruby SDK

Official Ruby SDK for BigDataCloud APIs. Strongly-typed client for IP Geolocation, Reverse Geocoding, Phone & Email Verification, and Network Engineering.

Zero external dependencies — stdlib net/http and json only.

Installation

gem install bigdatacloud

Or add to your Gemfile:

gem "bigdatacloud"

API Key

Get a free API key at bigdatacloud.com/login. No credit card required.

export BIGDATACLOUD_API_KEY=your-key-here

Quick Start

require "bigdatacloud"

# Reads BIGDATACLOUD_API_KEY from environment
client = BigDataCloud::Client.from_environment

# Or pass the key directly
# client = BigDataCloud::Client.new("your-key-here")

# IP Geolocation
geo = client.ip_geolocation.get(ip: "1.1.1.1")
puts "#{geo.location.city}, #{geo.country.name}"

# Reverse Geocoding
place = client.reverse_geocoding.reverse_geocode(-33.87, 151.21)
puts "#{place.city}, #{place.country_name}"

# Phone Validation — country_code is required
phone = client.verification.validate_phone("+61412345678", "AU")
puts "Valid: #{phone.is_valid}, Type: #{phone.line_type}"

# Email Verification
email = client.verification.verify_email("user@example.com")
puts "Valid: #{email.is_valid}, Disposable: #{email.is_disposable}"

Confidence Area

The confidence_area field may encode multiple polygons. Use the helper:

geo = client.ip_geolocation.get_with_confidence_area(ip: "1.1.1.1")
polygons = BigDataCloud::ConfidenceArea.split_into_polygons(geo.confidence_area)
polygons.each_with_index do |ring, i|
  puts "Ring #{i + 1}: #{ring.size} points"
end

Available APIs

Client	Methods
client.ip_geolocation	get, get_with_confidence_area, get_full, get_country_by_ip, get_country_info, get_all_countries, get_hazard_report, get_user_risk, get_asn_info, get_network_by_ip, get_timezone_by_iana_id, get_timezone_by_ip, parse_user_agent
client.reverse_geocoding	reverse_geocode, reverse_geocode_with_timezone, get_timezone_by_location
client.verification	validate_phone, validate_phone_by_ip, verify_email
client.network_engineering	get_asn_info_full, get_receiving_from, get_transit_to, get_bgp_prefixes, get_networks_by_cidr, get_asn_rank_list, get_tor_exit_nodes

Phone Validation

Both methods require explicit country context — never uses server IP silently:

# You know the country
phone = client.verification.validate_phone("+61412345678", "AU")

# You know the end user's IP (pass their IP, not your server's)
phone = client.verification.validate_phone_by_ip("0412345678", user_ip)

Error Handling

begin
  geo = client.ip_geolocation.get(ip: "1.1.1.1")
rescue BigDataCloud::Error => e
  puts "API error #{e.status_code}: #{e.message}"
end

Samples

export BIGDATACLOUD_API_KEY=your-key-here
ruby samples/ip_geolocation.rb
ruby samples/reverse_geocoding.rb
ruby samples/verification.rb
ruby samples/network_engineering.rb

License

MIT — see LICENSE.