GeoIP Enricher

This transformation enriches PostHog events and persons with IP location data. Simply enable this transformation and from that point on, your new events will have GeoIP data added, allowing you to locate users and run queries based on geographic data.

How it works

This transformation prefers to use event property $ip (which should be of type string), but if that is not provided, it uses the IP address of the client that sent the event.

This way the transformation can, in most cases, infer the IP address without any work on your side.

Requirements

Using this requires either PostHog Cloud with the data pipeline add-on, or a self-hosted PostHog instance running version 1.30.0 or later.

Self-hosting and not running 1.30.0? Find out how to update your self-hosted PostHog deployment.

Installation

Log in to your PostHog instance
Click "Data pipeline" in the left sidebar
Search for 'GeoIP'
Select the GeoIP transformation, press 'Install' and follow the on-screen instructions

Adding properties

The following properties can be added to the event if its IP address can be matched to a GeoLite2 City location:

TypeScript

$geoip_city_name?: string
$geoip_country_name?: string
$geoip_country_code?: string
$geoip_continent_name?: string
$geoip_continent_code?: string
$geoip_latitude?: number
$geoip_longitude?: number
$geoip_time_zone?: string
$geoip_subdivision_1_code?: string
$geoip_subdivision_1_name?: string
$geoip_subdivision_2_code?: string
$geoip_subdivision_2_name?: string
$geoip_subdivision_3_code?: string
$geoip_subdivision_3_name?: string

They are also set on the associated person same as above, plus setonce in `$initial_geoip...` form, to record where the user was when they were first seen.

How do I skip events without applying GeoIP enrichment?

A case to be aware of is sending events from a server – such events, if not provided with custom property $ip, will be detected as sent from the location of the data center, instead of the related user.

If you'd like this transformation to skip over an event and not add the above properties, set property $geoip_disable to true on that event.

FAQ

Is the source code for this transformation available?

PostHog is open-source and so are all transformations on the platform. The source code for the GeoIP Enricher is available on GitHub.

Who created this transformation?

We'd like to thank PostHog team members Yakko Majuri, Tim Glaser, Michael Matloka and former team member Paolo D'Amico for creating the GeoIP Enricher. We miss you, Paolo!