IP to Geo Enrichment

Keen can help enrich your events to include geo location data for your analysis and creation of map-based data visualizations. If you send us an IP address with the IP to Geo enrichment enabled, we can help give you more detailed geo data, like city, state/province, country, and more.

If you want to start using this enrichment right now while tracking pageviews, clicks, and form submissions, check out the Web Auto-Collector.

When this enrichment is being used, you can do analysis on 7 different location properties:

Property Description
city City associated with the client’s IP address.
province State/province associated with the client’s IP address.
country Country associated with the client’s IP address.
country_code ISO country code associated with the client’s IP address.
continent Continent associated with the client’s IP address.
postal_code Postal code associated with the client’s IP address.
coordinates List of geo coordinates, longitude followed by latitude.

To Activate IP to Geo Enrichment

The parameters for the IP to Geo enrichment are as follows:

Parameter Description
name “keen:ip_to_geo”
input An object with properties:
- A mandatory key of “ip” with a value of the name of the property containing the IP address to parse.
- An optional key “remove_ip_property” with a value true, to remove the “ip” property from the event, after the IP to GEO enrichment.

{ "ip": "property.containing.ip_address" } or
{ "ip": "property.containing.ip_address", "remove_ip_property": true }
output A property name describing where the produced object should be stored.
config An object containing the exclude_properties property, which is a list of property names you want to exclude from the output. Example: {"exclude_properties": ["city", "postal_code", "coordinates"]}

If geo information can’t be determined, output values will be null.

This enrichment can be used with the dynamic IP address placeholder.

You can take advantage of geo-filtering with the enriched coordinates property to deliver awesome map-based visualizations.

Your Event Data Model

To activate the enrichment, include the keen.addons object in your data model as seen below:

{
  "ip_address": "${keen.ip}",
  "keen": {
    "addons": [{
      "name": "keen:ip_to_geo",
      "input": {
        "ip": "ip_address"
      },
      "output": "ip_geo_info"
    }]
  }
}

The example above will create an output that looks like this:

{
  "ip_address": "192.168.0.1",
  "ip_geo_info": {
    "city": "San Francisco",
    "province": "California",
    "country": "United States",
    "country_code": "US",
    "continent": "North America",
    "postal_code": "94122",
    "coordinates": [-122.42005, 37.77479]
  },
  "keen": {
    "created_at": "2012-12-14T20:24:01.123000+00:00",
    "timestamp": "2012-12-14T20:24:01.123000+00:00",
    "id": "asd9fadifjaqw9asdfasdf939"
  }
}

You can also find the API Reference section for this enrichment here.

IP Anonymization

You can use the IP to Geo Enrichment without the need to store the ip address in an event. Add the "remove_ip_property": true to the input element as seen below:

{
  "ip_address": "${keen.ip}",
  "keen": {
    "addons": [{
      "name": "keen:ip_to_geo",
      "input": {
        "ip": "ip_address",
        "remove_ip_property": true
      },
      "output": "ip_geo_info"
    }]
  }
}

The example above will create an output that looks like this:

{
  "ip_geo_info": {
    "city": "San Francisco",
    "province": "California",
    "country": "United States",
    "country_code": "US",
    "continent": "North America",
    "postal_code": "94122",
    "coordinates": [-122.42005, 37.77479]
  },
  "keen": {
    "created_at": "2012-12-14T20:24:01.123000+00:00",
    "timestamp": "2012-12-14T20:24:01.123000+00:00",
    "id": "asd9fadifjaqw9asdfasdf939"
  }
}

Output Properties Removal

If you need extended anonymity options, use the exclude_properties functionality. It allows you to exclude output properties generated by the addon. You specify which output properties you want to be removed. Include this in the addon config object, as described below:

{
  "ip_address": "${keen.ip}",
  "keen": {
    "addons": [{
      "name": "keen:ip_to_geo",
      "input": {
        "ip": "ip_address"
      },
      "output": "ip_geo_info",
      "config": {
        "exclude_properties": ["coordinates", "city", "postal_code"]
      }
    }]
  }
}

The example above will create an output that looks like this:

{
  "ip_geo_info": {
    "province": "California",
    "country": "United States",
    "country_code": "US",
    "continent": "North America"
  },
  "ip_address": "0.0.0.0",
  "keen": {
    "created_at": "2012-12-14T20:24:01.123000+00:00",
    "timestamp": "2012-12-14T20:24:01.123000+00:00",
    "id": "asd9fadifjaqw9asdfasdf939"
  }
}

Examples

You can build a map-based data visualization with Keen and any mapping API or tool. Check out the Map Geo Coordinates guide and Geo-Explorer Dashboard for more info.

Count ip_geo_info.country group_by passed the results to Datamaps:

Group by Country map

Count ip_geo_info.city group_by:

Group by City