Update 6 April 2020: I updated the template in the gallery to the latest version of the IP Geolocation API SDK, which no longer requires jQuery. Also, the SDK now handles API request caching to browser storage automatically, so the “Enable Session Storage” option was added to the template.

My latest custom tag template tackles a use case I’ve referred to a number of times before, especially in my article on sending weather data to Google Analytics. The problem is two-fold:

  • How to fetch the user’s IP address into dataLayer
  • How to get latitude and longitude (as well as other geographical) data into dataLayer

For this purpose, I’ve created a new Google Tag Manager custom tag template that leverages the IP Geolocation API service. The API is inexpensive to use, and it offers HTTPS by default.

You can find the template in the template gallery.


The Simmer Newsletter

Subscribe to the Simmer newsletter to get the latest news and content from Simo Ahava into your email inbox!

IP Geolocation API

You can register for a free account at https://ipgeolocation.io/ to get an API key. If you register for a paid subscription, in addition to getting more quota (the free subscription only allows 1,000 requests per day), you’ll be able to use the template without exposing your API key to the public, so it’s something you should really consider if geolocation and/or IP resolution is what you want to do.

Sign up at https://ipgeolocation.io/signup.html.

Once you’ve signed up, you’ll find the dashboard with your API key. You’ll need this for the tag you create with the custom template.

If you’ve opted for a paid plan, you can add the origin (e.g. www.simoahava.com) to the list of Request Origins. If you do this, you don’t need to add the API key to the template.

Once you have the API key, and once you’ve downloaded the custom template into your container, you’re ready to proceed!

Create the tag

Create a new tag, and use IP Geolocation API as the template.

Then, fill in the tag fields. Make sure to add the API key fetched from your IP Geolocation API dashboard, unless you’ve added the origin where the tag will fire to the list of Request Origins (see previous chapter).

The other settings you can change are listed in the following chapters.

You can add whatever trigger you want to the tag. A trigger such as All Pages is OK, because it will resolve the API call as the earliest convenience. You can also use a more detailed rule to prevent the tag from firing on every single page, or to defer it until Window Loaded or similar.

The tag relies on the jQuery library. If your site doesn’t already use it, the template will automatically load the minified jQuery library along with the API SDK.

Data Layer Settings

If you’re using some other name for the dataLayer structure than dataLayer, you must type it into the Data Layer global variable name field, or the solution will not work properly.

The Custom event name field is where you can define what the value of the event key will be in the dataLayer object that contains the geolocation and IP address data.

The dataLayer object itself will be listed under the key geoData and will look something like this:

By the way, I am not in Salo, but in Espoo (some 100 kilometres distance). Geolocation is not a perfect art when using IP lookups.

IP Address Settings

The default is Client IP, which means it uses whatever public IP address is assigned to the machine in use.

If you want, you can also provide a Custom IP in case you’ve resolved the IP some other (more reliable, perhaps) way. The Custom IP can take a hard-coded value (not sure why you’d ever do so, though), or you can use a GTM variable for it. For example, to load the IP from a Data Layer Variable named DLV - user.ip, you could do this:

Other Settings

You can type a comma-separated list of fields to only include in the response by editing the Fields to include field.

The example above would only include the ip (always included), longitude, and latitude fields in the response.

Similarly, you can list fields you want to exclude from the response by editing the Fields to exclude field.

Finally, you can change the language of some of the response values by switching the Response language in the respective field. This might translate location names and other translatable values to the target language.

What to do with the data

Once you’ve got it up and running - what then?

Well, a new object will be populated in dataLayer using the custom event name you’ve set in the tag settings (geolocate by default). You can now fire tags that require IP or geolocation data using a Custom Event trigger for this event name.

The rest of the utilities would be Data Layer variables you create for the individual parts of the response you want to access. For example, a Data Layer variable for the user’s IP address would look like this:

A Data Layer Variable for the user’s latitude would look like this:

And so on and so forth.

You can use these for a variety of things:

  • Send geographical data to Google Analytics in order to benchmark the accuracy of the API or GA’s own geolocation lookups
  • Check the IP address against a range of “internal” IP addresses to flag the user as internal traffic using Google Tag Manager
  • Use the currency data to establish a local currency by default for the user
  • Use the isp and organization data to check ISP and network domain information about the user.


As always, there’s caveats galore with IP lookups. So many users use VPNs these days to (understandably) mask their location. This makes any type of geolocation and IP resolution extremely unreliable on a larger scale.

Similarly, even without a VPN, the accuracy is iffy at best. In the example used in the article, my location was resolved to be Salo, which is around 100 kilometres away from Espoo where the test data was generated.

So I wouldn’t put any UX value to this information - don’t redirect the user based on the API response, don’t tie any business critical logic to either IP or geolocation data, and don’t assume the API has an even passable success rate.

However, the use cases listed in the previous chapter are all more or less valid even with inaccurate data. You just need to shift your hypotheses from requiring exact, infallible answers to being satisfied with a broader spectrum of accuracy.

In any case, there are use cases for inspecting IP address and geolocation data within the browser. Some of them have been listed in the previous chapter. This custom template was created to help with these use cases.

Thank you for reading, and please share your questions, suggestions, and use cases in the comments of this article!