# 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](https://keen.io/docs/streams/web-auto-collection/).

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:<br> \- A **mandatory** key of “ip” with a value of the name of the property containing the IP address to parse.<br> \- An **optional** key “remove_ip_property” with a value true, to remove the “ip” property from the event, after the IP to GEO enrichment.<br>`{ "ip": "property.containing.ip_address" }` or<br>`{ "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](https://keen.io/docs/api/#dynamic-placeholders).

You can take advantage of [geo-filtering](https://keen.io/blog/introducing-geo-explorer-an-open-source-dashboard-for-tracking-app-usage-by-location/) 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](https://keen.io/docs/api/#ip-to-geo-parser).

### 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](https://keen.io/docs/visualize/map-geo-coordinates/) guide and [Geo-Explorer Dashboard](https://keen.io/blog/introducing-geo-explorer-an-open-source-dashboard-for-tracking-app-usage-by-location/) for more info.

Count `ip_geo_info.country``group_by` passed the results to [Datamaps](http://datamaps.github.io/):

Count `ip_geo_info.city``group_by`: