Creating ISO region codes for geo maps

This guide explains how to create a mapping table and a transformation script to create ISO region codes required for a geo map widget.

Introduction

A geo map widget can display a metric (such as Clicks or Impressions) as a regional heat map, where each region is displayed in a color that corresponds to amount of a selected metric value. In most cases, the higher the metric value, the stronger or warmer the displayed color.

To display the metric value in a region on a geo map, Adverity needs a dimension containing ISO region code data. This guide uses the country of Austria as an example.

The ISO region codes are added to a data extract using a mapping table and a transformation script.

This guide outlines how to create a mapping table and apply it to a datastream using the map custom script. However, this option is considered an advanced approach as it allows for a lot of customization. For an easier way to apply mapping tables to your datastream, consider using the Match & Map or Unify Location Data transformation. For more information on these transformations, see the following:

• Match & Map

• Unify Location Data

Creating a mapping table that contains ISO region codes

To create a mapping table that contains the ISO region codes for Austria, first, you need to create an empty mapping table and then import the ISO region codes into the empty mapping table.

Prerequisites

Before you read this reference, perform all of the following actions:

• Download the following CSV file that contains ISO region codes by clicking on the hyperlink below. This guide uses Austria as an example. To create a mapping table with ISO region codes for a different country, see Repository of ISO region codes for geo maps.

  • Austria ISO Region Codes

• Ensure the names of the regions in the mapping table match the names of the regions in the data source. If the names do not match, consider creating an additional mapping table to ensure the region names can be matched using the ISO region code mapping table. For more information, see Creating and applying mapping tables.

Procedure

To create a mapping table that contains the ISO region codes for Austria, follow these steps:

1. Go to the Transformations page.

2. Under the page heading, click Mapping Tables.

3. In the top right corner, click + Create Mapping Table.

4. In Name, provide a name for the mapping table. This guide uses Austria ISO region codes as an example.

5. To create the empty mapping table, click Save at the bottom of the page.

6. Click on the name of the mapping table you have just created.

7. In the secondary menu, click Import from CSV.

8. In Source, click Choose File and select the austria-iso-region-codes CSV file to import.

9. Click Upload.

As a result, a mapping table containing the region names and corresponding ISO region codes has been created.

Creating a transformation script to add ISO region codes to your data extract

Prerequisites

Before you read this reference, perform all of the following actions:

• Ensure the data source from which you are collecting data contains the following location fields:

  • Region name - This is used to map the region to the correct ISO Region code.

• Create a datastream to collect data from this data source. For more information, see Creating a datastream.

• Find the name of the columns in the data extract that contain the region names.

• Create a mapping table that contains the ISO region codes for the country to be displayed on the geo map widget. This guide uses Austria as an example. For more information, see Creating a mapping table that contains ISO region codes.

Procedure

To create a transformation script that adds ISO region codes to your data extract, follow these steps:

1. Go to the Transformations page.

2. In the top right corner, click + Create transformation.

3. Click Custom Script.

4. To assign the transformation to individual datastreams of your choice, follow these steps:

   1. In the Assign to section, select Individual datastreams.

   2. In the drop-down menu, select the datastreams to assign the transformation to them.

5. To assign the transformation to all existing and new datastreams that belong to Datastream Types of your choice, follow these steps:

   1. In the Assign to section, select Datastreams Types.

   2. In the drop-down menu, select the Datastream Types to assign the transformation to all datastreams that belong to these types.

   3. (Optional) In the Do not assign to these individual datastreams drop-down menu, select the individual datastreams that belong to the Datastream Types that you have selected, but you do not want to assign the transformation to them.

6. Click Next.

7. In Select Instruction, enter and select map.

8. In Sourcename, enter the name of the column in the data extract that contains the region names.

9. In Fieldname, enter the value iso-region-code. This is the name of the new column that will be created using the transformation instruction. This column will contain the ISO region codes.

10. In Mapping, enter the name of the mapping table containing the ISO regions codes. This guide uses a mapping table called Austria ISO region codes as an example.

11. In Missing, select create,stop.

12. In Errors, select raise.

13. Click Next.

14. (Optional) In Transformation name, rename the transformation.

15. Click Create +.

As a result, the mapping transformation script is created and can be applied to a datastream to add ISO region codes to your data extract.

Applying the transformation to a datastream

To apply the transformation to a datastream, follow these steps:

1. Go to the Datastreams page.

2. Click the datastream to which you want to apply the transformation.

3. In the Transformations section, click + Add transformation.

4. Click Assign Existing transformation.

5. To the right of the transformation you want to apply to the datastream, click + Assign

6. In the top right corner of the page, click Close to close the Assign transformations window.

As a result, the transformation script is added to the datastream. Click Fetch now to collect data in the datastream with the applied transformation script to add the ISO region codes to your data extract.

Loading data extracts that contain ISO region codes

To load the data extract that contains the ISO region codes dimension into Explore & Present, the datastream must contain Data Mapping. When setting up a Data Mapping, you may need to create a new target field for ISO region codes. For more information on creating this target field for the Data Mapping, see Mapping source fields.