IP Lookup Enrichment

Snowplow documentation

IP Lookup Enrichment¶

Summary¶

This enrichment uses MaxMind databases to look up useful data based on the IP address collected by your Snowplow tracker(s).

Overview¶

When a user browses your site or app their IP address is collected. MaxMind maintains databases of additional points of information like geographic location, second level domain names (acme.com), Internet Service Provider, organization name and several other data points publicly associated with a given IP address.

The IP lookup enrichment uses MaxMind databases in order to take the IP address collected and add additional data points to every event generated by the user with a given IP address.

For more information on this enrichment take a look here.

Some of the databases MaxMind maintains require a commercial subscription with MaxMind. The geolocation database GeoLite2 is hosted by Snowplow and is available for use by enabling this enrichment as in the example below.

Example¶

{
    "schema": "iglu:com.snowplowanalytics.snowplow/ip_lookups/jsonschema/2-0-0",
    "data": {
        "name": "ip_lookups",
        "vendor": "com.snowplowanalytics.snowplow",
        "enabled": true,
        "parameters": {
            "geo": {
                "database": "GeoLite2-City.mmdb",
                "uri": "http://snowplow-hosted-assets.s3.amazonaws.com/third-party/maxmind"
            }
        }
    }
}

In the configuration above, we are showing enabling this enrichment to take all IP addresses from each event and do a lookup against the GeoLite2-City.mmdb which is hosted by Snowplow at http://snowplow-hosted-assets.s3.amazonaws.com/third-party/maxmind.

The parameters to set start with the type of MaxMind database we are accessing (in this case the “geo” type). Then we specify the name of the database file, and the URI it’s available at.

If we were to enable this enrichment as shown, we would see the following columns in our data warehouse get populated with data for a user with the IP Address 37.157.33.178:

geo_city	geo_country	geo_latitude	geo_location	geo_longitude	geo_region	geo_region_name	geo_timezone	geo_zipcode
London	GB	51.5237	51.5237,-0.089	-0.089	ENG	England	Europe/London	EC2A

To extend this enrichment for the additional databases offered by Maxmind we would simply repeat the process for the other databases as such:

{
    "schema": "iglu:com.snowplowanalytics.snowplow/ip_lookups/jsonschema/2-0-0",
    "data": {
        "name": "ip_lookups",
        "vendor": "com.snowplowanalytics.snowplow",
        "enabled": true,
        "parameters": {
            "geo": {
                "database": "GeoIP2-City.mmdb",
                "uri": "s3://my-private-bucket/third-party/maxmind"
            },
            "isp": {
                "database": "GeoIP2-ISP.mmdb",
                "uri": "s3://my-private-bucket/third-party/maxmind"
            },
            "domain": {
                "database": "GeoIP2-Domain.mmdb",
                "uri": "s3://my-private-bucket/third-party/maxmind"
            },
            "connectionType": {
                "database": "GeoIP2-Connection-Type.mmdb",
                "uri": "s3://my-private-bucket/third-party/maxmind"
            }
        }
    }
}

The data from these databases would then be loaded into the following columns:

• ip_isp: ISP name

• ip_organization: Organization name for larger networks

• ip_domain: Second level domain name

• ip_netspeed: Indication of connection type (dial-up, cellular, cable/DSL)

For help on this or any other enrichment please contact [e-mail].