How to create Custom Lookup Tables into GTM

May 30, 2017 - Written by

Let’s take a step behind: what are Custom Lookup Tables? If you already know what we’re talking about and you can’t wait you can skip over and go directly to the trick!

What are Lookup Tables in Google Tag Manager? Among the different features offered by Google Tag Manager you can find the variable called Lookup Table. It basically allows you to associate to an input a specific output. What are the benefits of using Lookup Tables? They help you to manage swiftly a data set that will require high skills in merging javascripts, tags and so on. See the example below to better understand how it works. Imagine you have to manage different environments of a website to which different properties are assigned.

In that case the variable “Property” is set as Lookup Table and it receives as an input the {{Page Hostname}}. According to different {{Page Hostname}} variables, whether they are for example staging or production environments, the output will return the proper value of the web property.

A second example of using Lookup Tables is the event labels’ rewriting for a {{Click ID}} input as we intend to obtain an easily readable value into Google Analytics. But examples are almost countless, as many as are the input you can use.

When you are going to create your Lookup Tables remember two points:

  • Fields are case sensitive
  • We got an exact match between input and output

…and it can be sometimes a kind of limit.

Problem (solvable)

Lookup Tables, as mentioned above, work in “is equal to” mode and they can’t afford to group easily a wider set of values that should return the same output. As an example, I would like to obtain as an output the value “London” for each landing page of a location-based advertising campaign. Their URL slugs’ structures unfortunately are all different: e.g. “/London”, “/london”, “/LDN”. 5-6 records should be created and they should return the same value, “/London”. But if I increase the number of the locations the values inside the Lookup Table will increase exponentially, as well as possible human mistakes. Wouldn’t be great if the Lookup Table would accept inputs like “match regex” or “contains”?


The solution is included in the spreadsheet you can download right after the instructions below. This file is useful as it’s a real timesaver: you do not have to nest N tags or custom js and in addition you can use up to 7 matches between data. Let’s see the details.

When you open the file the first thing to do is to assign a name to your new variable (you can add up to 10 variables for each sheet).

Now you can choose the input among the variables available in the dropdown or  you can add the new variable you want to set in the sheet named CONFIG.

And here’s the twist: choose the more suitable match!

Now set the input (KEY) and the output (VALUE).

Once defined the matches key-value, go to the top-right and click on “Download GTM Lookup Table Custom Var” and then on “Download Container JSON”.

Download the file here (Based on the file created by

The first time you will use the spreadsheet, the tool will show the conventional window “Authorization Required”: the authorization is required only to download the JSON file. As an option you may copy the cell B1 into a .txt file and rename it to “.json”. At this point you’ll just have to import into GTM the file you downloaded. As usual, you log in to your GTM account, click Admin>Import Container> Select the downloaded file, workspace and merge tag – Rename> Continue. And that’s all, now you have a custom Lookup Table at your disposal!

Wait, but it isn’t a real Lookup Table! That’s correct it isn’t a standard Lookup Table but a js variable that acts as a Lookup Table. The “fake” Lookup Table is helpful when the “exact-match” does not support our final goal and it saves our time and money.






The variable obviously has some restrictions:

  • 399 key/value matches for each variable are afforded
  • if the values are in a huge number, the js variable is slightly slower if compared to a standard Lookup Table
  • if many output are matching an input, the Lookup Table returns only the first match

Which one to use then? It’s up to you to decide, according to your final goal 🙂


Leave a Reply

Your email address will not be published. Required fields are marked *

  • Analytics Boosters

    Vicolo Buranelli, 2
    31100 Treviso

  • Analytics Boosters
    United Kingdom

    41 Devonshire Street
    W1G 7AJ
    United Kingdom

  • Analytics Boosters
    United States

    80 S.W. 8th Street
    33130 - Miami
    United States of America


Contact us