Geolocation Enrichment using Transformations

The most reliable way to enrich events with geolocation information is using RudderStack’s Geolocation Enrichment at Source feature.

RudderStack supports enriching events with users’ geolocation information via transformations.

This guide walks you through the geolocation enrichment feature in detail.

Overview

You can add a geolocation service function (geolocation) in your transformation takes the IP address present in the event (request_ip) as an argument.

The transformation returns the following geolocation data once it runs successfully:

• City
• Country
• Region
• Location
• Postal code
• Timezone

RudderStack supports both JavaScript and Python transformations for this feature.

License

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.

For more information, see Maxmind license agreement.

Usage

If you’re hosting RudderStack on-premise, contact the Customer Success team to use this feature.

To use the geolocation service, add a new transformation as shown:

/***
 * This transformation enriches events with geolocation data using an IP-to-geolocation API powered by Maxmind, available from https://www.maxmind.com.
 * This allows you to easily query events based on geolocation data, e.g., country, city.
 ***/

export async function transformEvent(event, metadata) {
  if (event.request_ip) {
    try {
      if (!event.context) event.context = {};
      event.context.geo = await geolocation(event.request_ip);
    } catch (e) {
      log(e.message);
    }
  }

  return event;
}

def transformEvent(event, metadata):
    try:
        if event.get('request_ip'):
            res = geolocation(event["request_ip"])
            if not event.get('context', None):
                event['context'] = {}
            event['context']['geo'] = res
    except Exception as e:
        log(str(e))
    return event

In the above transformation, the geolocation service function (geolocation) takes the IP address present in the event (request_ip) as an argument. Once it runs successfully, it returns the following geolocation data:

• City
• Country
• Region
• Location
• Postal code
• Timezone

Note that:

• The geolocation data provided by RudderStack powered by Maxmind is not 100% accurate and varies by country. See the Maxmind website (link: https://www.maxmind.com/en/geoip2-city-accuracy-comparison) to get the accuracy information by country.

• RudderStack returns a 400 Bad Request error if you pass a malformed IP address.

• If you currently use a geolocation enrichment template, switching to this transformation will result in some schema changes:

  • RudderStack creates new columns for the IP addresses in your warehouse.
  • It stores the country code instead of country name.

FAQ

How is this feature different from the geolocation enrichment transformation template?

RudderStack’s geolocation service feature lets you enrich events with users’ geolocation information for a given IP address by leveraging the licensed GeoLite2 data created by MaxMind.

On the other hand, the geolocation enrichment template enriches events with geolocation data using an IP-to-geolocation API endpoint that you need to provide.

Questions? Contact us by email or on Slack