maxmind-geoip2 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +17 -0
  3. data/Gemfile +11 -0
  4. data/Gemfile.lock +70 -0
  5. data/LICENSE-APACHE +202 -0
  6. data/LICENSE-MIT +17 -0
  7. data/README.dev.md +4 -0
  8. data/README.md +326 -0
  9. data/Rakefile +14 -0
  10. data/lib/maxmind/geoip2.rb +4 -0
  11. data/lib/maxmind/geoip2/client.rb +313 -0
  12. data/lib/maxmind/geoip2/errors.rb +48 -0
  13. data/lib/maxmind/geoip2/model/abstract.rb +27 -0
  14. data/lib/maxmind/geoip2/model/anonymous_ip.rb +63 -0
  15. data/lib/maxmind/geoip2/model/asn.rb +39 -0
  16. data/lib/maxmind/geoip2/model/city.rb +75 -0
  17. data/lib/maxmind/geoip2/model/connection_type.rb +32 -0
  18. data/lib/maxmind/geoip2/model/country.rb +70 -0
  19. data/lib/maxmind/geoip2/model/domain.rb +32 -0
  20. data/lib/maxmind/geoip2/model/enterprise.rb +15 -0
  21. data/lib/maxmind/geoip2/model/insights.rb +14 -0
  22. data/lib/maxmind/geoip2/model/isp.rb +53 -0
  23. data/lib/maxmind/geoip2/reader.rb +277 -0
  24. data/lib/maxmind/geoip2/record/abstract.rb +22 -0
  25. data/lib/maxmind/geoip2/record/city.rb +38 -0
  26. data/lib/maxmind/geoip2/record/continent.rb +37 -0
  27. data/lib/maxmind/geoip2/record/country.rb +54 -0
  28. data/lib/maxmind/geoip2/record/location.rb +73 -0
  29. data/lib/maxmind/geoip2/record/maxmind.rb +17 -0
  30. data/lib/maxmind/geoip2/record/place.rb +28 -0
  31. data/lib/maxmind/geoip2/record/postal.rb +30 -0
  32. data/lib/maxmind/geoip2/record/represented_country.rb +23 -0
  33. data/lib/maxmind/geoip2/record/subdivision.rb +48 -0
  34. data/lib/maxmind/geoip2/record/traits.rb +200 -0
  35. data/maxmind-geoip2.gemspec +25 -0
  36. data/test/test_client.rb +424 -0
  37. data/test/test_model_country.rb +80 -0
  38. data/test/test_model_names.rb +47 -0
  39. data/test/test_reader.rb +459 -0
  40. metadata +116 -0
@@ -0,0 +1,22 @@
1
+ # frozen_string_literal: true
2
+
3
+ module MaxMind::GeoIP2::Record
4
+ # @!visibility private
5
+ class Abstract
6
+ def initialize(record)
7
+ @record = record
8
+ end
9
+
10
+ protected
11
+
12
+ def get(key)
13
+ if @record.nil? || !@record.key?(key)
14
+ return false if key.start_with?('is_')
15
+
16
+ return nil
17
+ end
18
+
19
+ @record[key]
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,38 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/place'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # City-level data associated with an IP address.
7
+ #
8
+ # This record is returned by all location services and databases besides
9
+ # Country.
10
+ #
11
+ # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
12
+ class City < Place
13
+ # A value from 0-100 indicating MaxMind's confidence that the city is
14
+ # correct. This attribute is only available from the Insights service and
15
+ # the GeoIP2 Enterprise database.
16
+ #
17
+ # @return [Integer, nil]
18
+ def confidence
19
+ get('confidence')
20
+ end
21
+
22
+ # The GeoName ID for the city. This attribute is returned by all location
23
+ # services and databases.
24
+ #
25
+ # @return [Integer, nil]
26
+ def geoname_id
27
+ get('geoname_id')
28
+ end
29
+
30
+ # A Hash where the keys are locale codes and the values are names. This
31
+ # attribute is returned by all location services and databases.
32
+ #
33
+ # @return [Hash<String, String>, nil]
34
+ def names
35
+ get('names')
36
+ end
37
+ end
38
+ end
@@ -0,0 +1,37 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/place'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the continent record associated with an IP address.
7
+ #
8
+ # This record is returned by all location services and databases.
9
+ #
10
+ # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
11
+ class Continent < Place
12
+ # A two character continent code like "NA" (North America) or "OC"
13
+ # (Oceania). This attribute is returned by all location services and
14
+ # databases.
15
+ #
16
+ # @return [String, nil]
17
+ def code
18
+ get('code')
19
+ end
20
+
21
+ # The GeoName ID for the continent. This attribute is returned by all
22
+ # location services and databases.
23
+ #
24
+ # @return [String, nil]
25
+ def geoname_id
26
+ get('geoname_id')
27
+ end
28
+
29
+ # A Hash where the keys are locale codes and the values are names. This
30
+ # attribute is returned by all location services and databases.
31
+ #
32
+ # @return [Hash<String, String>, nil]
33
+ def names
34
+ get('names')
35
+ end
36
+ end
37
+ end
@@ -0,0 +1,54 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/place'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the country record associated with an IP address.
7
+ #
8
+ # This record is returned by all location services and databases.
9
+ #
10
+ # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
11
+ class Country < Place
12
+ # A value from 0-100 indicating MaxMind's confidence that the country is
13
+ # correct. This attribute is only available from the Insights service and
14
+ # the GeoIP2 Enterprise database.
15
+ #
16
+ # @return [Integer, nil]
17
+ def confidence
18
+ get('confidence')
19
+ end
20
+
21
+ # The GeoName ID for the country. This attribute is returned by all
22
+ # location services and databases.
23
+ #
24
+ # @return [Integer, nil]
25
+ def geoname_id
26
+ get('geoname_id')
27
+ end
28
+
29
+ # This is true if the country is a member state of the European Union. This
30
+ # attribute is returned by all location services and databases.
31
+ #
32
+ # @return [Boolean]
33
+ def in_european_union?
34
+ get('is_in_european_union')
35
+ end
36
+
37
+ # The two-character ISO 3166-1 alpha code for the country. See
38
+ # https://en.wikipedia.org/wiki/ISO_3166-1. This attribute is returned by
39
+ # all location services and databases.
40
+ #
41
+ # @return [String, nil]
42
+ def iso_code
43
+ get('iso_code')
44
+ end
45
+
46
+ # A Hash where the keys are locale codes and the values are names. This
47
+ # attribute is returned by all location services and databases.
48
+ #
49
+ # @return [Hash<String, String>, nil]
50
+ def names
51
+ get('names')
52
+ end
53
+ end
54
+ end
@@ -0,0 +1,73 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/abstract'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the location record associated with an IP address.
7
+ #
8
+ # This record is returned by all location services and databases besides
9
+ # Country.
10
+ class Location < Abstract
11
+ # The approximate accuracy radius in kilometers around the latitude and
12
+ # longitude for the IP address. This is the radius where we have a 67%
13
+ # confidence that the device using the IP address resides within the circle
14
+ # centered at the latitude and longitude with the provided radius.
15
+ #
16
+ # @return [Integer, nil]
17
+ def accuracy_radius
18
+ get('accuracy_radius')
19
+ end
20
+
21
+ # The average income in US dollars associated with the requested IP
22
+ # address. This attribute is only available from the Insights service.
23
+ #
24
+ # @return [Integer, nil]
25
+ def average_income
26
+ get('average_income')
27
+ end
28
+
29
+ # The approximate latitude of the location associated with the IP address.
30
+ # This value is not precise and should not be used to identify a particular
31
+ # address or household.
32
+ #
33
+ # @return [Float, nil]
34
+ def latitude
35
+ get('latitude')
36
+ end
37
+
38
+ # The approximate longitude of the location associated with the IP address.
39
+ # This value is not precise and should not be used to identify a particular
40
+ # address or household.
41
+ #
42
+ # @return [Float, nil]
43
+ def longitude
44
+ get('longitude')
45
+ end
46
+
47
+ # The metro code of the location if the location is in the US. MaxMind
48
+ # returns the same metro codes as the Google AdWords API. See
49
+ # https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions.
50
+ #
51
+ # @return [Integer, nil]
52
+ def metro_code
53
+ get('metro_code')
54
+ end
55
+
56
+ # The estimated population per square kilometer associated with the IP
57
+ # address. This attribute is only available from the Insights service.
58
+ #
59
+ # @return [Integer, nil]
60
+ def population_density
61
+ get('population_density')
62
+ end
63
+
64
+ # The time zone associated with location, as specified by the IANA Time
65
+ # Zone Database, e.g., "America/New_York". See
66
+ # https://www.iana.org/time-zones.
67
+ #
68
+ # @return [String, nil]
69
+ def time_zone
70
+ get('time_zone')
71
+ end
72
+ end
73
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/abstract'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data about your account.
7
+ #
8
+ # This record is returned by all location services.
9
+ class MaxMind < Abstract
10
+ # The number of remaining queries you have for the service you are calling.
11
+ #
12
+ # @return [Integer, nil]
13
+ def queries_remaining
14
+ get('queries_remaining')
15
+ end
16
+ end
17
+ end
@@ -0,0 +1,28 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/abstract'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Location data common to different location types.
7
+ class Place < Abstract
8
+ # @!visibility private
9
+ def initialize(record, locales)
10
+ super(record)
11
+ @locales = locales
12
+ end
13
+
14
+ # The first available localized name in order of preference.
15
+ #
16
+ # @return [String, nil]
17
+ def name
18
+ n = names
19
+ return nil if n.nil?
20
+
21
+ @locales.each do |locale|
22
+ return n[locale] if n.key?(locale)
23
+ end
24
+
25
+ nil
26
+ end
27
+ end
28
+ end
@@ -0,0 +1,30 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/abstract'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the postal record associated with an IP address.
7
+ #
8
+ # This record is returned by all location services and databases besides
9
+ # Country.
10
+ class Postal < Abstract
11
+ # The postal code of the location. Postal codes are not available for all
12
+ # countries. In some countries, this will only contain part of the postal
13
+ # code. This attribute is returned by all location databases and services
14
+ # besides Country.
15
+ #
16
+ # @return [String, nil]
17
+ def code
18
+ get('code')
19
+ end
20
+
21
+ # A value from 0-100 indicating MaxMind's confidence that the postal code
22
+ # is correct. This attribute is only available from the Insights service
23
+ # and the GeoIP2 Enterprise database.
24
+ #
25
+ # @return [Integer, nil]
26
+ def confidence
27
+ get('confidence')
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,23 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/country'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the represented country associated with an IP address.
7
+ #
8
+ # This class contains the country-level data associated with an IP address
9
+ # for the IP's represented country. The represented country is the country
10
+ # represented by something like a military base.
11
+ #
12
+ # See {MaxMind::GeoIP2::Record::Country} for inherited methods.
13
+ class RepresentedCountry < Country
14
+ # A string indicating the type of entity that is representing the country.
15
+ # Currently we only return +military+ but this could expand to include
16
+ # other types in the future.
17
+ #
18
+ # @return [String, nil]
19
+ def type
20
+ get('type')
21
+ end
22
+ end
23
+ end
@@ -0,0 +1,48 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'maxmind/geoip2/record/place'
4
+
5
+ module MaxMind::GeoIP2::Record
6
+ # Contains data for the subdivisions associated with an IP address.
7
+ #
8
+ # This record is returned by all location databases and services besides
9
+ # Country.
10
+ #
11
+ # See {MaxMind::GeoIP2::Record::Place} for inherited methods.
12
+ class Subdivision < Place
13
+ # This is a value from 0-100 indicating MaxMind's confidence that the
14
+ # subdivision is correct. This attribute is only available from the
15
+ # Insights service and the GeoIP2 Enterprise database.
16
+ #
17
+ # @return [Integer, nil]
18
+ def confidence
19
+ get('confidence')
20
+ end
21
+
22
+ # This is a GeoName ID for the subdivision. This attribute is returned by
23
+ # all location databases and services besides Country.
24
+ #
25
+ # @return [Integer, nil]
26
+ def geoname_id
27
+ get('geoname_id')
28
+ end
29
+
30
+ # This is a string up to three characters long contain the subdivision
31
+ # portion of the ISO 3166-2 code. See
32
+ # https://en.wikipedia.org/wiki/ISO_3166-2. This attribute is returned by
33
+ # all location databases and services except Country.
34
+ #
35
+ # @return [String, nil]
36
+ def iso_code
37
+ get('iso_code')
38
+ end
39
+
40
+ # A Hash where the keys are locale codes and the values are names. This attribute is returned by all location services and
41
+ # databases besides country.
42
+ #
43
+ # @return [Hash<String, String>, nil]
44
+ def names
45
+ get('names')
46
+ end
47
+ end
48
+ end
@@ -0,0 +1,200 @@
1
+ # frozen_string_literal: true
2
+
3
+ require 'ipaddr'
4
+ require 'maxmind/geoip2/record/abstract'
5
+
6
+ module MaxMind::GeoIP2::Record
7
+ # Contains data for the traits record associated with an IP address.
8
+ #
9
+ # This record is returned by all location services and databases.
10
+ class Traits < Abstract
11
+ # @!visibility private
12
+ def initialize(record)
13
+ super(record)
14
+ if !record.key?('network') && record.key?('ip_address') &&
15
+ record.key?('prefix_length')
16
+ ip = IPAddr.new(record['ip_address']).mask(record['prefix_length'])
17
+ # We could use ip.prefix instead of record['prefix_length'], but that
18
+ # method only becomes available in Ruby 2.5+.
19
+ record['network'] = format('%s/%d', ip.to_s, record['prefix_length'])
20
+ end
21
+ end
22
+
23
+ # The autonomous system number associated with the IP address. See
24
+ # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
25
+ # This attribute is only available from the City and Insights web service
26
+ # and the GeoIP2 Enterprise database.
27
+ #
28
+ # @return [Integer, nil]
29
+ def autonomous_system_number
30
+ get('autonomous_system_number')
31
+ end
32
+
33
+ # The organization associated with the registered autonomous system number
34
+ # for the IP address. See
35
+ # Wikipedia[https://en.wikipedia.org/wiki/Autonomous_system_(Internet)].
36
+ # This attribute is only available from the City and Insights web service
37
+ # and the GeoIP2 Enterprise database.
38
+ #
39
+ # @return [String, nil]
40
+ def autonomous_system_organization
41
+ get('autonomous_system_organization')
42
+ end
43
+
44
+ # The connection type may take the following values: "Dialup",
45
+ # "Cable/DSL", "Corporate", "Cellular". Additional values may be added in
46
+ # the future. This attribute is only available in the GeoIP2 Enterprise
47
+ # database.
48
+ #
49
+ # @return [String, nil]
50
+ def connection_type
51
+ get('connection_type')
52
+ end
53
+
54
+ # The second level domain associated with the IP address. This will be
55
+ # something like "example.com" or "example.co.uk", not "foo.example.com".
56
+ # This attribute is only available from the City and Insights web service
57
+ # and the GeoIP2 Enterprise database.
58
+ #
59
+ # @return [String, nil]
60
+ def domain
61
+ get('domain')
62
+ end
63
+
64
+ # The IP address that the data in the model is for. If you performed a "me"
65
+ # lookup against the web service, this will be the externally routable IP
66
+ # address for the system the code is running on. If the system is behind a
67
+ # NAT, this may differ from the IP address locally assigned to it. This
68
+ # attribute is returned by all end points.
69
+ #
70
+ # @return [String]
71
+ def ip_address
72
+ get('ip_address')
73
+ end
74
+
75
+ # This is true if the IP address belongs to any sort of anonymous network.
76
+ # This property is only available from GeoIP2 Precision Insights.
77
+ #
78
+ # @return [Boolean]
79
+ def anonymous?
80
+ get('is_anonymous')
81
+ end
82
+
83
+ # This is true if the IP address is registered to an anonymous VPN
84
+ # provider. If a VPN provider does not register subnets under names
85
+ # associated with them, we will likely only flag their IP ranges using the
86
+ # hosting_provider? property. This property is only available from GeoIP2
87
+ # Precision Insights.
88
+ #
89
+ # @return [Boolean]
90
+ def anonymous_vpn?
91
+ get('is_anonymous_vpn')
92
+ end
93
+
94
+ # This is true if the IP address belongs to a hosting or VPN provider (see
95
+ # description of the anonymous_vpn? property). This property is only
96
+ # available from GeoIP2 Precision Insights.
97
+ #
98
+ # @return [Boolean]
99
+ def hosting_provider?
100
+ get('is_hosting_provider')
101
+ end
102
+
103
+ # This attribute is true if MaxMind believes this IP address to be a
104
+ # legitimate proxy, such as an internal VPN used by a corporation. This
105
+ # attribute is only available in the GeoIP2 Enterprise database.
106
+ #
107
+ # @return [Boolean]
108
+ def legitimate_proxy?
109
+ get('is_legitimate_proxy')
110
+ end
111
+
112
+ # This is true if the IP address belongs to a public proxy. This property
113
+ # is only available from GeoIP2 Precision Insights.
114
+ #
115
+ # @return [Boolean]
116
+ def public_proxy?
117
+ get('is_public_proxy')
118
+ end
119
+
120
+ # This is true if the IP address is a Tor exit node. This property is only
121
+ # available from GeoIP2 Precision Insights.
122
+ #
123
+ # @return [Boolean]
124
+ def tor_exit_node?
125
+ get('is_tor_exit_node')
126
+ end
127
+
128
+ # The name of the ISP associated with the IP address. This attribute is
129
+ # only available from the City and Insights web services and the GeoIP2
130
+ # Enterprise database.
131
+ #
132
+ # @return [String, nil]
133
+ def isp
134
+ get('isp')
135
+ end
136
+
137
+ # The network in CIDR notation associated with the record. In particular,
138
+ # this is the largest network where all of the fields besides ip_address
139
+ # have the same value.
140
+ #
141
+ # @return [String]
142
+ def network
143
+ get('network')
144
+ end
145
+
146
+ # The name of the organization associated with the IP address. This
147
+ # attribute is only available from the City and Insights web services and
148
+ # the GeoIP2 Enterprise database.
149
+ #
150
+ # @return [String, nil]
151
+ def organization
152
+ get('organization')
153
+ end
154
+
155
+ # An indicator of how static or dynamic an IP address is. This property is
156
+ # only available from GeoIP2 Precision Insights.
157
+ #
158
+ # @return [Float, nil]
159
+ def static_ip_score
160
+ get('static_ip_score')
161
+ end
162
+
163
+ # The estimated number of users sharing the IP/network during the past 24
164
+ # hours. For IPv4, the count is for the individual IP. For IPv6, the count
165
+ # is for the /64 network. This property is only available from GeoIP2
166
+ # Precision Insights.
167
+ #
168
+ # @return [Integer, nil]
169
+ def user_count
170
+ get('user_count')
171
+ end
172
+
173
+ # The user type associated with the IP address. This can be one of the
174
+ # following values:
175
+ #
176
+ # * business
177
+ # * cafe
178
+ # * cellular
179
+ # * college
180
+ # * content_delivery_network
181
+ # * dialup
182
+ # * government
183
+ # * hosting
184
+ # * library
185
+ # * military
186
+ # * residential
187
+ # * router
188
+ # * school
189
+ # * search_engine_spider
190
+ # * traveler
191
+ #
192
+ # This attribute is only available from the Insights web service and the
193
+ # GeoIP2 Enterprise database.
194
+ #
195
+ # @return [String, nil]
196
+ def user_type
197
+ get('user_type')
198
+ end
199
+ end
200
+ end