maxmind-geoip2 0.3.0

data/lib/maxmind/geoip2/record/abstract.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # @!visibility private
+      class Abstract
+        def initialize(record)
+          @record = record
+        end
+
+        protected
+
+        def get(key)
+          if @record.nil? || !@record.key?(key)
+            return false if key.start_with?('is_')
+
+            return nil
+          end
+
+          @record[key]
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/city.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # City-level data associated with an IP address.
+      #
+      # This record is returned by all location services and databases besides
+      # Country.
+      #
+      # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
+      class City < Place
+        # A value from 0-100 indicating MaxMind's confidence that the city is
+        # correct. This attribute is only available from the Insights service and
+        # the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+
+        # The GeoName ID for the city. This attribute is returned by all location
+        # services and databases.
+        #
+        # @return [Integer, nil]
+        def geoname_id
+          get('geoname_id')
+        end
+
+        # A Hash where the keys are locale codes and the values are names. This
+        # attribute is returned by all location services and databases.
+        #
+        # @return [Hash<String, String>, nil]
+        def names
+          get('names')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/continent.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the continent record associated with an IP address.
+      #
+      # This record is returned by all location services and databases.
+      #
+      # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
+      class Continent < Place
+        # A two character continent code like "NA" (North America) or "OC"
+        # (Oceania). This attribute is returned by all location services and
+        # databases.
+        #
+        # @return [String, nil]
+        def code
+          get('code')
+        end
+
+        # The GeoName ID for the continent. This attribute is returned by all
+        # location services and databases.
+        #
+        # @return [String, nil]
+        def geoname_id
+          get('geoname_id')
+        end
+
+        # A Hash where the keys are locale codes and the values are names. This
+        # attribute is returned by all location services and databases.
+        #
+        # @return [Hash<String, String>, nil]
+        def names
+          get('names')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/country.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the country record associated with an IP address.
+      #
+      # This record is returned by all location services and databases.
+      #
+      # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
+      class Country < Place
+        # A value from 0-100 indicating MaxMind's confidence that the country is
+        # correct. This attribute is only available from the Insights service and
+        # the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+
+        # The GeoName ID for the country. This attribute is returned by all
+        # location services and databases.
+        #
+        # @return [Integer, nil]
+        def geoname_id
+          get('geoname_id')
+        end
+
+        # This is true if the country is a member state of the European Union. This
+        # attribute is returned by all location services and databases.
+        #
+        # @return [Boolean]
+        def in_european_union?
+          get('is_in_european_union')
+        end
+
+        # The two-character ISO 3166-1 alpha code for the country. See
+        # https://en.wikipedia.org/wiki/ISO_3166-1. This attribute is returned by
+        # all location services and databases.
+        #
+        # @return [String, nil]
+        def iso_code
+          get('iso_code')
+        end
+
+        # A Hash where the keys are locale codes and the values are names. This
+        # attribute is returned by all location services and databases.
+        #
+        # @return [Hash<String, String>, nil]
+        def names
+          get('names')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/location.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the location record associated with an IP address.
+      #
+      # This record is returned by all location services and databases besides
+      # Country.
+      class Location < Abstract
+        # The approximate accuracy radius in kilometers around the latitude and
+        # longitude for the IP address. This is the radius where we have a 67%
+        # confidence that the device using the IP address resides within the circle
+        # centered at the latitude and longitude with the provided radius.
+        #
+        # @return [Integer, nil]
+        def accuracy_radius
+          get('accuracy_radius')
+        end
+
+        # The average income in US dollars associated with the requested IP
+        # address. This attribute is only available from the Insights service.
+        #
+        # @return [Integer, nil]
+        def average_income
+          get('average_income')
+        end
+
+        # The approximate latitude of the location associated with the IP address.
+        # This value is not precise and should not be used to identify a particular
+        # address or household.
+        #
+        # @return [Float, nil]
+        def latitude
+          get('latitude')
+        end
+
+        # The approximate longitude of the location associated with the IP address.
+        # This value is not precise and should not be used to identify a particular
+        # address or household.
+        #
+        # @return [Float, nil]
+        def longitude
+          get('longitude')
+        end
+
+        # The metro code of the location if the location is in the US. MaxMind
+        # returns the same metro codes as the Google AdWords API. See
+        # https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions.
+        #
+        # @return [Integer, nil]
+        def metro_code
+          get('metro_code')
+        end
+
+        # The estimated population per square kilometer associated with the IP
+        # address. This attribute is only available from the Insights service.
+        #
+        # @return [Integer, nil]
+        def population_density
+          get('population_density')
+        end
+
+        # The time zone associated with location, as specified by the IANA Time
+        # Zone Database, e.g., "America/New_York". See
+        # https://www.iana.org/time-zones.
+        #
+        # @return [String, nil]
+        def time_zone
+          get('time_zone')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/maxmind.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data about your account.
+      #
+      # This record is returned by all location services.
+      class MaxMind < Abstract
+        # The number of remaining queries you have for the service you are calling.
+        #
+        # @return [Integer, nil]
+        def queries_remaining
+          get('queries_remaining')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/place.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Location data common to different location types.
+      class Place < Abstract
+        # @!visibility private
+        def initialize(record, locales)
+          super(record)
+          @locales = locales
+        end
+
+        # The first available localized name in order of preference.
+        #
+        # @return [String, nil]
+        def name
+          n = names
+          return nil if n.nil?
+
+          @locales.each do |locale|
+            return n[locale] if n.key?(locale)
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/postal.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the postal record associated with an IP address.
+      #
+      # This record is returned by all location services and databases besides
+      # Country.
+      class Postal < Abstract
+        # The postal code of the location. Postal codes are not available for all
+        # countries. In some countries, this will only contain part of the postal
+        # code. This attribute is returned by all location databases and services
+        # besides Country.
+        #
+        # @return [String, nil]
+        def code
+          get('code')
+        end
+
+        # A value from 0-100 indicating MaxMind's confidence that the postal code
+        # is correct. This attribute is only available from the Insights service
+        # and the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/represented_country.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/country'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the represented country associated with an IP address.
+      #
+      # This class contains the country-level data associated with an IP address
+      # for the IP's represented country. The represented country is the country
+      # represented by something like a military base.
+      #
+      # See {MaxMind::GeoIP2::Record::Country} for inherited methods.
+      class RepresentedCountry < Country
+        # A string indicating the type of entity that is representing the country.
+        # Currently we only return +military+ but this could expand to include
+        # other types in the future.
+        #
+        # @return [String, nil]
+        def type
+          get('type')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/subdivision.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'maxmind/geoip2/record/place'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the subdivisions associated with an IP address.
+      #
+      # This record is returned by all location databases and services besides
+      # Country.
+      #
+      # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
+      class Subdivision < Place
+        # This is a value from 0-100 indicating MaxMind's confidence that the
+        # subdivision is correct. This attribute is only available from the
+        # Insights service and the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def confidence
+          get('confidence')
+        end
+
+        # This is a GeoName ID for the subdivision. This attribute is returned by
+        # all location databases and services besides Country.
+        #
+        # @return [Integer, nil]
+        def geoname_id
+          get('geoname_id')
+        end
+
+        # This is a string up to three characters long contain the subdivision
+        # portion of the ISO 3166-2 code. See
+        # https://en.wikipedia.org/wiki/ISO_3166-2. This attribute is returned by
+        # all location databases and services except Country.
+        #
+        # @return [String, nil]
+        def iso_code
+          get('iso_code')
+        end
+
+        # A Hash where the keys are locale codes and the values are names. This attribute is returned by all location services and
+        # databases besides country.
+        #
+        # @return [Hash<String, String>, nil]
+        def names
+          get('names')
+        end
+      end
+    end
+  end
+end

data/lib/maxmind/geoip2/record/traits.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require 'ipaddr'
+require 'maxmind/geoip2/record/abstract'
+
+module MaxMind
+  module GeoIP2
+    module Record
+      # Contains data for the traits record associated with an IP address.
+      #
+      # This record is returned by all location services and databases.
+      class Traits < Abstract
+        # @!visibility private
+        def initialize(record)
+          super(record)
+          if !record.key?('network') && record.key?('ip_address') &&
+             record.key?('prefix_length')
+            ip = IPAddr.new(record['ip_address']).mask(record['prefix_length'])
+            # We could use ip.prefix instead of record['prefix_length'], but that
+            # method only becomes available in Ruby 2.5+.
+            record['network'] = format('%s/%d', ip.to_s, record['prefix_length'])
+          end
+        end
+
+        # The autonomous system number associated with the IP address. See
+        # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
+        # This attribute is only available from the City and Insights web service
+        # and the GeoIP2 Enterprise database.
+        #
+        # @return [Integer, nil]
+        def autonomous_system_number
+          get('autonomous_system_number')
+        end
+
+        # The organization associated with the registered autonomous system number
+        # for the IP address. See
+        # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
+        # This attribute is only available from the City and Insights web service
+        # and the GeoIP2 Enterprise database.
+        #
+        # @return [String, nil]
+        def autonomous_system_organization
+          get('autonomous_system_organization')
+        end
+
+        # The connection type may take the following  values: "Dialup",
+        # "Cable/DSL", "Corporate", "Cellular". Additional values may be added in
+        # the future. This attribute is only available in the GeoIP2 Enterprise
+        # database.
+        #
+        # @return [String, nil]
+        def connection_type
+          get('connection_type')
+        end
+
+        # The second level domain associated with the IP address. This will be
+        # something like "example.com" or "example.co.uk", not "foo.example.com".
+        # This attribute is only available from the City and Insights web service
+        # and the GeoIP2 Enterprise database.
+        #
+        # @return [String, nil]
+        def domain
+          get('domain')
+        end
+
+        # The IP address that the data in the model is for. If you performed a "me"
+        # lookup against the web service, this will be the externally routable IP
+        # address for the system the code is running on. If the system is behind a
+        # NAT, this may differ from the IP address locally assigned to it. This
+        # attribute is returned by all end points.
+        #
+        # @return [String]
+        def ip_address
+          get('ip_address')
+        end
+
+        # This is true if the IP address belongs to any sort of anonymous network.
+        # This property is only available from GeoIP2 Precision Insights.
+        #
+        # @return [Boolean]
+        def anonymous?
+          get('is_anonymous')
+        end
+
+        # This is true if the IP address is registered to an anonymous VPN
+        # provider. If a VPN provider does not register subnets under names
+        # associated with them, we will likely only flag their IP ranges using the
+        # hosting_provider? property. This property is only available from GeoIP2
+        # Precision Insights.
+        #
+        # @return [Boolean]
+        def anonymous_vpn?
+          get('is_anonymous_vpn')
+        end
+
+        # This is true if the IP address belongs to a hosting or VPN provider (see
+        # description of the anonymous_vpn? property). This property is only
+        # available from GeoIP2 Precision Insights.
+        #
+        # @return [Boolean]
+        def hosting_provider?
+          get('is_hosting_provider')
+        end
+
+        # This attribute is true if MaxMind believes this IP address to be a
+        # legitimate proxy, such as an internal VPN used by a corporation. This
+        # attribute is only available in the GeoIP2 Enterprise database.
+        #
+        # @return [Boolean]
+        def legitimate_proxy?
+          get('is_legitimate_proxy')
+        end
+
+        # This is true if the IP address belongs to a public proxy. This property
+        # is only available from GeoIP2 Precision Insights.
+        #
+        # @return [Boolean]
+        def public_proxy?
+          get('is_public_proxy')
+        end
+
+        # This is true if the IP address is a Tor exit node. This property is only
+        # available from GeoIP2 Precision Insights.
+        #
+        # @return [Boolean]
+        def tor_exit_node?
+          get('is_tor_exit_node')
+        end
+
+        # The name of the ISP associated with the IP address. This attribute is
+        # only available from the City and Insights web services and the GeoIP2
+        # Enterprise database.
+        #
+        # @return [String, nil]
+        def isp
+          get('isp')
+        end
+
+        # The network in CIDR notation associated with the record. In particular,
+        # this is the largest network where all of the fields besides ip_address
+        # have the same value.
+        #
+        # @return [String]
+        def network
+          get('network')
+        end
+
+        # The name of the organization associated with the IP address. This
+        # attribute is only available from the City and Insights web services and
+        # the GeoIP2 Enterprise database.
+        #
+        # @return [String, nil]
+        def organization
+          get('organization')
+        end
+
+        # An indicator of how static or dynamic an IP address is. This property is
+        # only available from GeoIP2 Precision Insights.
+        #
+        # @return [Float, nil]
+        def static_ip_score
+          get('static_ip_score')
+        end
+
+        # The estimated number of users sharing the IP/network during the past 24
+        # hours. For IPv4, the count is for the individual IP. For IPv6, the count
+        # is for the /64 network. This property is only available from GeoIP2
+        # Precision Insights.
+        #
+        # @return [Integer, nil]
+        def user_count
+          get('user_count')
+        end
+
+        # The user type associated with the IP address. This can be one of the
+        # following values:
+        #
+        # * business
+        # * cafe
+        # * cellular
+        # * college
+        # * content_delivery_network
+        # * dialup
+        # * government
+        # * hosting
+        # * library
+        # * military
+        # * residential
+        # * router
+        # * school
+        # * search_engine_spider
+        # * traveler
+        #
+        # This attribute is only available from the Insights web service and the
+        # GeoIP2 Enterprise database.
+        #
+        # @return [String, nil]
+        def user_type
+          get('user_type')
+        end
+      end
+    end
+  end
+end