ipdata 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ecd1e1860fb3d422c8aea50274e10528dd45d12c4555de9585e7af64f06de450
+  data.tar.gz: f7ad0dcf1f3fd4a526e5ebe64b901c848f4c5cab432ebe33d0a897f72f9c500d
+SHA512:
+  metadata.gz: 5c3e379a60cd06fc5a5e38aca4680d2014c6b2324bd2587cb108310c0c1356cfc294bd2082ed1d3278e4b7950e5df1c0ff0d7da89be6f40d2b307e63eebdf0e9
+  data.tar.gz: 18f91231a4c26f1c3ba5f2e86436eff0ca22a2b8078f9749af994ace74de4707c4c95d0416344ed658ca186504bdbb3ebfbdec669466ce00d8c6c1a095ad8377

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 IPData
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,235 @@
+# IPData Ruby SDK
+
+Official Ruby client for the [ipdata.co](https://ipdata.co) IP geolocation API. Look up geolocation, threat intelligence, ASN, company, carrier, currency, timezone, and language data for any IP address.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ipdata"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install ipdata
+```
+
+## Quick Start
+
+Get a free API key at [ipdata.co/sign-up](https://ipdata.co/sign-up.html) (1,500 requests/day).
+
+```ruby
+require "ipdata"
+
+client = IPData::Client.new("YOUR_API_KEY")
+
+# Look up an IP address
+response = client.lookup("8.8.8.8")
+
+response.ip           # => "8.8.8.8"
+response.city         # => "Mountain View"
+response.country_name # => "United States"
+response.latitude     # => 37.386
+response.longitude    # => -122.0838
+```
+
+## Usage
+
+### Look Up Your Own IP
+
+```ruby
+response = client.lookup
+response.ip # => your public IP
+```
+
+### Look Up a Specific IP
+
+```ruby
+response = client.lookup("1.1.1.1")
+response.country_name # => "Australia"
+response.asn.name     # => "Cloudflare, Inc."
+response.asn.asn      # => "AS13335"
+```
+
+### Select Specific Fields
+
+Reduce payload by requesting only the fields you need:
+
+```ruby
+response = client.lookup("8.8.8.8", fields: ["ip", "city", "country_name"])
+response.city # => "Mountain View"
+```
+
+### Extract a Single Field
+
+```ruby
+city = client.lookup("8.8.8.8", select_field: "city")
+# => "Mountain View"
+```
+
+### Bulk Lookup
+
+Look up multiple IPs in a single request (max 100):
+
+```ruby
+responses = client.bulk_lookup(["8.8.8.8", "1.1.1.1"])
+responses.each do |r|
+  puts "#{r.ip}: #{r.country_name}"
+end
+```
+
+Bulk lookup also supports field filtering:
+
+```ruby
+responses = client.bulk_lookup(
+  ["8.8.8.8", "1.1.1.1"],
+  fields: ["ip", "country_name", "city"]
+)
+```
+
+### EU Endpoint (GDPR Compliant)
+
+Route requests through EU data centers only:
+
+```ruby
+client = IPData::Client.eu("YOUR_API_KEY")
+```
+
+### Caching
+
+Enable an in-memory LRU cache to reduce API calls:
+
+```ruby
+cache = IPData::Cache.new(max_size: 1024, ttl: 3600) # 1h TTL
+client = IPData::Client.new("YOUR_API_KEY", cache: cache)
+
+client.lookup("8.8.8.8") # hits API
+client.lookup("8.8.8.8") # served from cache
+```
+
+### Custom Timeout
+
+```ruby
+client = IPData::Client.new("YOUR_API_KEY", timeout: 10) # 10 seconds
+```
+
+## Response Fields
+
+All responses are wrapped in `IPData::Response` objects that support both dot-notation and hash-style access:
+
+```ruby
+response = client.lookup("8.8.8.8")
+
+# Dot notation
+response.ip
+response.city
+response.region
+response.country_name
+response.country_code
+response.continent_name
+response.latitude
+response.longitude
+response.is_eu
+response.postal
+response.calling_code
+response.flag
+response.emoji_flag
+response.emoji_unicode
+
+# Nested objects
+response.asn.asn          # => "AS15169"
+response.asn.name         # => "Google LLC"
+response.asn.domain       # => "google.com"
+response.asn.route        # => "8.8.8.0/24"
+response.asn.type         # => "business"
+
+response.company.name
+response.company.domain
+response.company.network
+response.company.type
+
+response.carrier.name
+response.carrier.mcc
+response.carrier.mnc
+
+response.currency.name
+response.currency.code
+response.currency.symbol
+response.currency.native
+response.currency.plural
+
+response.time_zone.name
+response.time_zone.abbr
+response.time_zone.offset
+response.time_zone.is_dst
+response.time_zone.current_time
+
+response.threat.is_tor
+response.threat.is_vpn
+response.threat.is_icloud_relay
+response.threat.is_proxy
+response.threat.is_datacenter
+response.threat.is_anonymous
+response.threat.is_known_attacker
+response.threat.is_known_abuser
+response.threat.is_threat
+response.threat.is_bogon
+response.threat.blocklists
+response.threat.scores
+
+# Languages (array)
+response.languages.first.name
+response.languages.first.native
+response.languages.first.code
+
+# Hash-style access
+response["city"]
+response[:country_code]
+
+# Raw hash
+response.to_h
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.lookup("8.8.8.8")
+rescue IPData::AuthenticationError => e
+  # Missing API key (401)
+  puts "Auth error: #{e.message} (#{e.status_code})"
+rescue IPData::ForbiddenError => e
+  # Invalid key or quota exceeded (403)
+  puts "Forbidden: #{e.message} (#{e.status_code})"
+rescue IPData::BadRequestError => e
+  # Invalid IP or bad request (400)
+  puts "Bad request: #{e.message} (#{e.status_code})"
+rescue IPData::Error => e
+  # Any other API error
+  puts "Error: #{e.message} (#{e.status_code})"
+end
+```
+
+## Requirements
+
+- Ruby >= 3.0
+- No runtime dependencies (uses only Ruby stdlib)
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+## License
+
+[MIT](LICENSE)

data/lib/ipdata/cache.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module IPData
+  # Thread-safe LRU cache with TTL expiration.
+  #
+  # Used to cache IP lookup results and avoid redundant API calls.
+  # Uses Ruby's stdlib Monitor for thread safety.
+  #
+  # @example
+  #   cache = IPData::Cache.new(max_size: 1024, ttl: 3600)
+  #   client = IPData::Client.new("KEY", cache: cache)
+  class Cache
+    Entry = Struct.new(:value, :expires_at)
+
+    DEFAULT_MAX_SIZE = 4096
+    DEFAULT_TTL = 86_400 # 24 hours
+
+    def initialize(max_size: DEFAULT_MAX_SIZE, ttl: DEFAULT_TTL)
+      @max_size = max_size
+      @ttl = ttl
+      @store = {}
+      @monitor = Monitor.new
+    end
+
+    # Retrieve a cached value. Returns nil if missing or expired.
+    def get(key)
+      @monitor.synchronize do
+        entry = @store[key]
+        return nil unless entry
+
+        if Time.now > entry.expires_at
+          @store.delete(key)
+          return nil
+        end
+
+        # Move to end (most recently used) by re-inserting
+        @store.delete(key)
+        @store[key] = entry
+        entry.value
+      end
+    end
+
+    # Store a value in the cache. Evicts the least recently used entry
+    # if the cache is at capacity.
+    def set(key, value)
+      @monitor.synchronize do
+        @store.delete(key) # remove if exists (re-insert at end)
+
+        # Evict LRU entry if at capacity
+        if @store.size >= @max_size
+          lru_key = @store.keys.first
+          @store.delete(lru_key)
+        end
+
+        @store[key] = Entry.new(value, Time.now + @ttl)
+      end
+    end
+
+    # Remove all entries.
+    def clear
+      @monitor.synchronize { @store.clear }
+    end
+
+    # Number of entries currently cached.
+    def size
+      @monitor.synchronize { @store.size }
+    end
+  end
+end

data/lib/ipdata/client.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module IPData
+  # HTTP client for the ipdata.co API.
+  #
+  # @example Basic usage
+  #   client = IPData::Client.new("YOUR_API_KEY")
+  #   response = client.lookup("8.8.8.8")
+  #   response.city  # => "Mountain View"
+  #
+  # @example EU endpoint (GDPR compliant)
+  #   client = IPData::Client.eu("YOUR_API_KEY")
+  #
+  # @example With caching
+  #   cache = IPData::Cache.new(max_size: 1024, ttl: 3600)
+  #   client = IPData::Client.new("YOUR_API_KEY", cache: cache)
+  class Client
+    BASE_URL = "https://api.ipdata.co"
+    EU_BASE_URL = "https://eu-api.ipdata.co"
+
+    # @param api_key [String] Your ipdata API key
+    # @param cache [IPData::Cache, nil] Optional LRU cache instance
+    # @param timeout [Integer] HTTP timeout in seconds (default: 30)
+    # @param base_url [String, nil] Override the base URL (default: global endpoint)
+    def initialize(api_key, cache: nil, timeout: 30, base_url: nil)
+      raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @cache = cache
+      @timeout = timeout
+      @base_uri = URI.parse(base_url || BASE_URL)
+    end
+
+    # Create a client configured for the EU endpoint.
+    #
+    # @param api_key [String] Your ipdata API key
+    # @param opts [Hash] Additional options passed to {#initialize}
+    # @return [Client]
+    def self.eu(api_key, **opts)
+      new(api_key, base_url: EU_BASE_URL, **opts)
+    end
+
+    # Look up geolocation data for an IP address.
+    #
+    # @param ip [String, nil] IP address to look up (nil for caller's own IP)
+    # @param fields [Array<String>, nil] Specific fields to return
+    # @param select_field [String, nil] A single field to extract (returns raw value)
+    # @return [Response, Object] Response object, or raw value if select_field is used
+    def lookup(ip = nil, fields: nil, select_field: nil)
+      if select_field
+        path = "/#{ip}/#{select_field}"
+        data = get(path)
+        return data
+      end
+
+      cache_key = build_cache_key(ip, fields)
+      if @cache
+        cached = @cache.get(cache_key)
+        return cached if cached
+      end
+
+      path = ip ? "/#{ip}" : "/"
+      params = {}
+      params["fields"] = fields.join(",") if fields && !fields.empty?
+
+      data = get(path, params)
+      response = Response.new(data)
+
+      @cache&.set(cache_key, response)
+      response
+    end
+
+    # Look up geolocation data for multiple IP addresses.
+    #
+    # @param ips [Array<String>] IP addresses (max 100)
+    # @param fields [Array<String>, nil] Specific fields to return
+    # @return [Array<Response>]
+    # @raise [ArgumentError] if more than 100 IPs are provided
+    def bulk_lookup(ips, fields: nil)
+      raise ArgumentError, "ips must be an Array" unless ips.is_a?(Array)
+      raise ArgumentError, "maximum 100 IPs per bulk request" if ips.size > 100
+
+      params = {}
+      params["fields"] = fields.join(",") if fields && !fields.empty?
+
+      data = post("/bulk", ips, params)
+      data.map { |entry| Response.new(entry) }
+    end
+
+    private
+
+    def user_agent
+      @user_agent ||= "ruby-ipdata/#{VERSION} Ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+    end
+
+    def build_cache_key(ip, fields)
+      key = ip || "_self"
+      key = "#{key}:#{fields.sort.join(",")}" if fields && !fields.empty?
+      key
+    end
+
+    def build_uri(path, params = {})
+      uri = @base_uri.dup
+      uri.path = path
+      query_params = { "api-key" => @api_key }.merge(params)
+      uri.query = URI.encode_www_form(query_params)
+      uri
+    end
+
+    def get(path, params = {})
+      uri = build_uri(path, params)
+
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = user_agent
+
+      execute(uri, request)
+    end
+
+    def post(path, body, params = {})
+      uri = build_uri(path, params)
+
+      request = Net::HTTP::Post.new(uri)
+      request["Accept"] = "application/json"
+      request["Content-Type"] = "application/json"
+      request["User-Agent"] = user_agent
+      request.body = JSON.generate(body)
+
+      execute(uri, request)
+    end
+
+    def execute(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Error.from_response(response.code.to_i, response.body)
+      end
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/ipdata/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module IPData
+  # Base error class for all ipdata API errors.
+  # Carries the HTTP status code and API error message.
+  class Error < StandardError
+    attr_reader :status_code
+
+    def initialize(message, status_code = nil)
+      @status_code = status_code
+      super(message)
+    end
+
+    # Build the appropriate error subclass from an HTTP response.
+    def self.from_response(status, body)
+      message = parse_message(body) || "API request failed"
+      klass = case status
+              when 400 then BadRequestError
+              when 401 then AuthenticationError
+              when 403 then ForbiddenError
+              else Error
+              end
+      klass.new(message, status)
+    end
+
+    def self.parse_message(body)
+      return nil if body.nil? || body.empty?
+
+      data = JSON.parse(body)
+      data["message"]
+    rescue JSON::ParserError
+      body
+    end
+    private_class_method :parse_message
+  end
+
+  # Raised when the API key is missing (HTTP 401).
+  class AuthenticationError < Error; end
+
+  # Raised when the API key is invalid or quota is exceeded (HTTP 403).
+  class ForbiddenError < Error; end
+
+  # Raised for invalid IP addresses or malformed requests (HTTP 400).
+  class BadRequestError < Error; end
+end

data/lib/ipdata/response.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+
+module IPData
+  # Lightweight wrapper around the parsed API JSON response.
+  #
+  # Provides both dot-notation and hash-style access:
+  #   response.city          # => "Mountain View"
+  #   response["city"]       # => "Mountain View"
+  #   response[:city]        # => "Mountain View"
+  #   response.asn.name      # => "Google LLC"
+  #   response.threat.is_vpn # => false
+  #
+  # Nested hashes are recursively wrapped as Response objects.
+  # Arrays of hashes (e.g. languages, blocklists) are mapped to Response arrays.
+  class Response
+    def initialize(data)
+      @data = data || {}
+    end
+
+    # Hash-style access. Accepts string or symbol keys.
+    def [](key)
+      wrap(@data[key.to_s])
+    end
+
+    # Returns the underlying raw Hash.
+    def to_h
+      @data
+    end
+
+    # Serialize back to JSON.
+    def to_json(*)
+      JSON.generate(@data)
+    end
+
+    def to_s
+      @data.to_s
+    end
+
+    def inspect
+      "#<#{self.class} #{@data.inspect}>"
+    end
+
+    # Returns true if the key exists in the response data.
+    def key?(key)
+      @data.key?(key.to_s)
+    end
+
+    # Iterate over key-value pairs.
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def ==(other)
+      case other
+      when Response then @data == other.to_h
+      when Hash then @data == other
+      else false
+      end
+    end
+
+    private
+
+    def wrap(value)
+      case value
+      when Hash then Response.new(value)
+      when Array then value.map { |v| wrap(v) }
+      else value
+      end
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if @data.key?(key)
+        wrap(@data[key])
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @data.key?(name.to_s) || super
+    end
+  end
+end

data/lib/ipdata/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IPData
+  VERSION = "0.1.5"
+end

data/lib/ipdata.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "ipdata/version"
+require_relative "ipdata/errors"
+require_relative "ipdata/response"
+require_relative "ipdata/cache"
+require_relative "ipdata/client"

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ipdata
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- IPData
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-23 00:00:00.000000000 Z
+dependencies: []
+description: Official Ruby SDK for the ipdata.co API. Look up geolocation, threat
+  intelligence, ASN, company, carrier, currency, timezone and language data for any
+  IP address.
+email:
+- support@ipdata.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ipdata.rb
+- lib/ipdata/cache.rb
+- lib/ipdata/client.rb
+- lib/ipdata/errors.rb
+- lib/ipdata/response.rb
+- lib/ipdata/version.rb
+homepage: https://github.com/ipdata/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ipdata/ruby
+  source_code_uri: https://github.com/ipdata/ruby
+  changelog_uri: https://github.com/ipdata/ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ipdata/ruby/issues
+  documentation_uri: https://docs.ipdata.co
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the ipdata IP geolocation API
+test_files: []