GeoIP Lookup (MaxMind)

This graph allows Xponent to integrate with MaxMind GeoIP2 Precision Services, a geo IP lookup service, to look for demographic and geo-location information about a specific IP address. This requires an account with MaxMind, which charges for three different tiers of lookups. This service offers varying levels of precision based on price ($0.0001 to $0.002 per lookup). 

There are a variety of 3rd party IP Lookup APIs available with varying prices (including free), information returned, and rate limits. All provide a similar service and have similar setups; our advice is to be wary of free accounts as there are no service reliability promises and often lower rate limits.

This template will call MaxMind for the IP details and cache them in an IP lookup table for one week. IP address ownership can change at any time. Therefore, the geo data is not constant. It would be quite costly and time-consuming to look up a user's IP address for every web event and store the exact same information in your database; therefore, caching the IP Geo data in a lookup table is both efficient and economical.

Explaining Geo IP Lookup to a client

Every user accessing the internet does so from a network access point e.g. WiFi/ LAN. These networks have an associated address set by the internet provider. 

Since Internet Service Providers (ISPs) tend to operate out of specific geographic locations and also provide service to specific geographic locations, and because the pool of addresses allocated to the ISPs are distributed within the geographic region in which they operate, it is possible to map geographic regions to the discrete IP address. 

Finding out the location of a user visiting your website or using your app can be extremely useful when segmenting customers and tailoring personalization; however, there are some caveats and limitations to using this data. I highly recommend researching the top results from this Google Search here.

Package contents

• Graphs: 
  • Refresh App Params Graph Template
  • Get Geo IP Lookup (MaxMind)
  • Call Geo IP Lookup (MaxMind)
• Schema

{
	"maxmind": {
		"result": {
			"city": {
				"names": {
					"de": "Los Angeles",
					"en": "Los Angeles",
					"es": "Los Ángeles",
					"fr": "Los Angeles",
					"ja": "ロサンゼルス市",
					"ru": "Лос-Анджелес",
					"pt-BR": "Los Angeles",
					"zh-CN": "洛杉矶"
				},
				"confidence": 25,
				"geoname_id": 54321
			},
			"postal": {
				"code": "90001",
				"confidence": 10
			},
			"traits": {
				"isp": "Linkem spa",
				"domain": "example.com",
				"user_type": "traveler",
				"ip_address": "1.2.3.4",
				"organization": "Linkem IR WiMax Network",
				"is_anonymous_proxy": true,
				"is_satellite_provider": true,
				"autonomous_system_number": 1239,
				"autonomous_system_organization": "Linkem IR WiMax Network"
			},
			"country": {
				"names": {
					"de": "USA",
					"en": "United States",
					"es": "Estados Unidos",
					"fr": "États-Unis",
					"ja": "アメリカ合衆国",
					"ru": "США",
					"pt-BR": "Estados Unidos",
					"zh-CN": "美国"
				},
				"iso_code": "US",
				"confidence": 75,
				"geoname_id": 6252001
			},
			"maxmind": {
				"queries_remaining": 54321
			},
			"location": {
				"latitude": 37.6293,
				"longitude": -122.1163,
				"time_zone": "America/Los_Angeles",
				"metro_code": 807,
				"average_income": 128321,
				"accuracy_radius": 20,
				"population_density": 7122
			},
			"continent": {
				"code": "NA",
				"names": {
					"de": "Nordamerika",
					"en": "North America",
					"es": "América del Norte",
					"fr": "Amérique du Nord",
					"ja": "北アメリカ",
					"ru": "Северная Америка",
					"pt-BR": "América do Norte",
					"zh-CN": "北美洲"
				},
				"geoname_id": 123456
			},
			"subdivisions": {
				"names": {
					"de": "Kalifornien",
					"en": "California",
					"es": "California",
					"fr": "Californie",
					"ja": "カリフォルニア",
					"ru": "Калифорния",
					"zh-CN": "加州"
				},
				"iso_code": "CA",
				"confidence": 50,
				"geoname_id": 5332921
			},
			"registered_country": {
				"names": {
					"de": "USA",
					"en": "United States",
					"es": "Estados Unidos",
					"fr": "États-Unis",
					"ja": "アメリカ合衆国",
					"ru": "США",
					"pt-BR": "Estados Unidos",
					"zh-CN": "美国"
				},
				"iso_code": "US",
				"geoname_id": 6252001
			},
			"represented_country": {
				"type": "military",
				"names": {
					"de": "USA",
					"en": "United States",
					"es": "Estados Unidos",
					"fr": "États-Unis",
					"ja": "アメリカ合衆国",
					"ru": "США",
					"pt-BR": "Estados Unidos",
					"zh-CN": "美国"
				},
				"iso_code": "US",
				"geoname_id": 6252001
			}
		},
		"ipAddress": "",
		"requestType": "",
		"authorizationHeader": ""
	}
}

Setup 

• Create a MaxMind account.
• Deploy the Maxmind template.
  

• Configure the MaxMind REST Web Service connection with the following details:
  
• Endpoint: https://geoip.maxmind.com/geoip/v2.1/

• In Maxmind, generate a license key for your application.
• Follow the instructions for the setup of the Application Parameters Graph Template.

• Insert the MaxMind credentials into the appParams table using the following SQL:

INSERT INTO appParams(paramKey,paramValue,paramType,description) VALUES
('maxMindLicenceKey', 'LICENSE KEY GOES HERE', 'string', 'This is the access token for MaxMind'),
('maxMindUserId', 'USER ID GOES HERE', 'string', 'This is the user id for MaxMind');

Create chanIPGeoLkup

CREATE TABLE chanIPGeoLkup (
  ip varchar(20) NOT NULL,
  tsCreated datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  country text,
  registered_country text,
  represented_country text,
  continent text,
  city text,
  postal text,
  traits text,
  location text,
  subdivisions text,
  PRIMARY KEY (ip,tsCreated),
  UNIQUE KEY primunique (ip,tsCreated)
);

Using

• Ensure there is credit in the MaxMind account to pay for the lookups.
  • MaxMind has an auto top-up feature (recommended) or a manual payment capability.
  • The MaxMind web service adaptor will error if there is insufficient credit.
• Place the Get GeoIPLkup (MaxMind) graph in your graph.
  • The expected outputs for this graph are true, 'metaSet'. The parent graph should also accommodate GoTo and Error.
• Set graph parameter "requestType" to 'city', 'country' or 'insights'. The default is the country.
  
• Set  the graph parameter "ip" to the IP to be looked up.
• The authorizationHeader will be built out using the credentials stored in the appParams table.
• The result of the MaxMind Geo IP lookup is stored in  "{schema}.maxmind.result" and saved in the chanIPLookup table.
• Test the graph using the following JSON:

{
	"maxmind": {
		"ipAddress": "176.12.107.140",
		"requestType":"country"
	}
}

Notes:

What is likely to go wrong

• Run out of MaxMind credit.
  • Ensure you have credit in your account.
• The web service adaptor returns 500.
  • Double-check that you have configured your connection settings correctly. Check the URL. by copying from the adaptor node:
    
  • And pasting it into your browser to get the following response:
    

Typical Deliverables Plan

1. Client to configure the MaxMind account and provide Licence Key and User Key to KW user.
2. KW user to deploy MaxMind graph template and required environments.
3. Create SQL Assets:
   1. If using your own database.
      1. KW user to create SQL assets.
   2. If using the client's database:
      1. Provide the SQL creation code above for the brand to create
      2. KW will need access to the database - see here for DB connections
4. KW User to deploy the graph