Class: MaxMind::GeoIP2::Client

Inherits:

Object

Object
MaxMind::GeoIP2::Client

show all

Defined in:: lib/maxmind/geoip2/client.rb

Overview

This class provides a client API for all the GeoIP2 web services. The services are Country, City Plus, and Insights. Each service returns a different set of data about an IP address, with Country returning the least data and Insights the most.

Each web service is represented by a different model class, and these model classes in turn contain multiple record classes. The record classes have attributes which contain data about the IP address.

If the web service does not return a particular piece of data for an IP address, the associated attribute is not populated.

The web service may not return any information for an entire record, in which case all of the attributes for that record class will be empty.

Usage

The basic API for this class is the same for all of the web service end points. First you create a web service client object with your MaxMind account ID and license key, then you call the method corresponding to a specific end point, passing it the IP address you want to look up.

If the request succeeds, the method call will return a model class for the service you called. This model in turn contains multiple record classes, each of which represents part of the data returned by the web service.

If the request fails, the client class throws an exception.

Example

require 'maxmind/geoip2'

client = MaxMind::GeoIP2::Client.new(
  account_id: 42,
  license_key: 'abcdef123456',
)

# Replace 'city' with the method corresponding to the web service you
# are using, e.g., 'country', 'insights'.
record = client.city('128.101.101.101')

puts record.country.iso_code

Instance Method Summary collapse

#city(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::City

This method calls the City Plus web service.
#country(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::Country

This method calls the Country web service.
#initialize(account_id:, license_key:, locales: ['en'], host: 'geoip.maxmind.com', timeout: 0, proxy_address: '', proxy_port: 0, proxy_username: '', proxy_password: '', pool_size: 5) ⇒ Client constructor

Create a Client that may be used to query a GeoIP2 web service.
#insights(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::Insights

This method calls the Insights web service.

Constructor Details

#initialize(account_id:, license_key:, locales: ['en'], host: 'geoip.maxmind.com', timeout: 0, proxy_address: '', proxy_port: 0, proxy_username: '', proxy_password: '', pool_size: 5) ⇒ `Client`

Create a Client that may be used to query a GeoIP2 web service.

Once created, the Client is safe to use for lookups from multiple threads.

Parameters:

account_id (Integer) —

your MaxMind account ID.
license_key (String) —

your MaxMind license key.
locales (Array<String>) (defaults to: ['en']) —

a list of locale codes to use in the name property from most preferred to least preferred.
host (String) (defaults to: 'geoip.maxmind.com') —

the host to use when querying the web service. Set this to “geolite.info” to use the GeoLite2 web service instead of the GeoIP2 web service. Set this to “sandbox.maxmind.com” to use the Sandbox environment. The sandbox allows you to experiment with the API without affecting your production data.
timeout (Integer) (defaults to: 0) —

the number of seconds to wait for a request before timing out. If 0, no timeout is set.
proxy_address (String) (defaults to: '') —

proxy address to use, if any.
proxy_port (Integer) (defaults to: 0) —

proxy port to use, if any.
proxy_username (String) (defaults to: '') —

proxy username to use, if any.
proxy_password (String) (defaults to: '') —

proxy password to use, if any.
pool_size (Integer) (defaults to: 5) —

HTTP connection pool size

# File 'lib/maxmind/geoip2/client.rb', line 93

def initialize(
  account_id:,
  license_key:,
  locales: ['en'],
  host: 'geoip.maxmind.com',
  timeout: 0,
  proxy_address: '',
  proxy_port: 0,
  proxy_username: '',
  proxy_password: '',
  pool_size: 5
)
  @account_id = account_id
  @license_key = license_key
  @locales = locales || ['en']
  @host = host || 'geoip.maxmind.com'
  @timeout = timeout || 0
  @proxy_address = proxy_address || ''
  @proxy_port = proxy_port || 0
  @proxy_username = proxy_username || ''
  @proxy_password = proxy_password || ''
  @pool_size = pool_size || 5

  @connection_pool = ConnectionPool.new(size: @pool_size) do
    make_http_client.persistent("https://#{@host}")
  end
end

Instance Method Details

#city(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::City`

This method calls the City Plus web service.

Parameters:

ip_address (String) (defaults to: 'me') —

IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from is used.

Returns:

(MaxMind::GeoIP2::Model::City)

Raises:

(HTTP::Error) —

if there was an error performing the HTTP request, such as an error connecting.
(JSON::ParserError) —

if there was invalid JSON in the response.
(HTTPError) —

if there was a problem with the HTTP response, such as an unexpected HTTP status code.
(AddressInvalidError) —

if the web service believes the IP address to be invalid or missing.
(AddressNotFoundError) —

if the IP address was not found.
(AddressReservedError) —

if the IP address is reserved.
(AuthenticationError) —

if there was a problem authenticating to the web service, such as an invalid or missing license key.
(InsufficientFundsError) —

if your account is out of credit.
(PermissionRequiredError) —

if your account does not have permission to use the web service.
(InvalidRequestError) —

if the web service responded with an error and there is no more specific error to raise.



157
158
159

# File 'lib/maxmind/geoip2/client.rb', line 157

def city(ip_address = 'me')
  response_for('city', MaxMind::GeoIP2::Model::City, ip_address)
end

#country(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::Country`

This method calls the Country web service.

Parameters:

ip_address (String) (defaults to: 'me') —

IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from is used.

Returns:

(MaxMind::GeoIP2::Model::Country)

Raises:

(HTTP::Error) —

if there was an error performing the HTTP request, such as an error connecting.
(JSON::ParserError) —

if there was invalid JSON in the response.
(HTTPError) —

if there was a problem with the HTTP response, such as an unexpected HTTP status code.
(AddressInvalidError) —

if the web service believes the IP address to be invalid or missing.
(AddressNotFoundError) —

if the IP address was not found.
(AddressReservedError) —

if the IP address is reserved.
(AuthenticationError) —

if there was a problem authenticating to the web service, such as an invalid or missing license key.
(InsufficientFundsError) —

if your account is out of credit.
(PermissionRequiredError) —

if your account does not have permission to use the web service.
(InvalidRequestError) —

if the web service responded with an error and there is no more specific error to raise.



194
195
196

# File 'lib/maxmind/geoip2/client.rb', line 194

def country(ip_address = 'me')
  response_for('country', MaxMind::GeoIP2::Model::Country, ip_address)
end

#insights(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::Insights`

This method calls the Insights web service.

Insights is only supported by the GeoIP2 web service. The GeoLite2 web service does not support it.

Parameters:

ip_address (String) (defaults to: 'me') —

IPv4 or IPv6 address as a string. If no address is provided, the address that the web service is called from is used.

Returns:

(MaxMind::GeoIP2::Model::Insights)

Raises:

(HTTP::Error) —

if there was an error performing the HTTP request, such as an error connecting.
(JSON::ParserError) —

if there was invalid JSON in the response.
(HTTPError) —

if there was a problem with the HTTP response, such as an unexpected HTTP status code.
(AddressInvalidError) —

if the web service believes the IP address to be invalid or missing.
(AddressNotFoundError) —

if the IP address was not found.
(AddressReservedError) —

if the IP address is reserved.
(AuthenticationError) —

if there was a problem authenticating to the web service, such as an invalid or missing license key.
(InsufficientFundsError) —

if your account is out of credit.
(PermissionRequiredError) —

if your account does not have permission to use the web service.
(InvalidRequestError) —

if the web service responded with an error and there is no more specific error to raise.



234
235
236

# File 'lib/maxmind/geoip2/client.rb', line 234

def insights(ip_address = 'me')
  response_for('insights', MaxMind::GeoIP2::Model::Insights, ip_address)
end

Class: MaxMind::GeoIP2::Client

Overview

Usage

Example

Instance Method Summary collapse

Constructor Details

#initialize(account_id:, license_key:, locales: ['en'], host: 'geoip.maxmind.com', timeout: 0, proxy_address: '', proxy_port: 0, proxy_username: '', proxy_password: '', pool_size: 5) ⇒ Client

Instance Method Details

#city(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::City

#country(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::Country

#insights(ip_address = 'me') ⇒ MaxMind::GeoIP2::Model::Insights

#initialize(account_id:, license_key:, locales: ['en'], host: 'geoip.maxmind.com', timeout: 0, proxy_address: '', proxy_port: 0, proxy_username: '', proxy_password: '', pool_size: 5) ⇒ `Client`

#city(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::City`

#country(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::Country`

#insights(ip_address = 'me') ⇒ `MaxMind::GeoIP2::Model::Insights`