Creating geolocation transformation scripts

This guide explains how to create a transformation script that will create a geolocation dimension.

Introduction

A geo map widget displays a metric (such as Clicks or Impressions) on a map, showing where the metric took place. To display the location of a metric on a geo map, Adverity needs a dimension containing geolocation data.

This geolocation dimension is created by combining the values of latitude and longitude into a single value. This combination is achieved using a transformation script.

The transformation script you need to create contains two instructions:

• addfieldx - In this example, this instruction combines the latitude and longitude values into a single value, geolocation.

• convertx - In this example, this instruction converts geolocation into a decimal string, a format that Adverity can read to plot the locations on a geo map.

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

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:

  • Latitude (required for the creation of the geolocation dimension)

  • Longitude (required for the creation of the geolocation dimension)

• (Optional) To increase performance, ensure the latitude and longitude values are set to no more than two decimal places. This is achieved through a transformation script. If you wish to round the latitude and longitude values, ensure the rounding script is run before the geolocation-creation script. For more information see, Creating rounding transformation script.

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

• Find the names of the columns in the data extract that contain the latitude and longitude values.

Procedure

To create a transformation script that combines latitude and longitude into a single value that is also in the correct format, 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 addfieldx.

8. In Fieldname, enter the value geolocation. This is the name of the new column that will be created using the transformation instruction.

9. In Python Expression, enter the following code. Replace the values of latitude and longitude with the corresponding latitude and longitude names from the data extract (For example, these names could be lat and long, or lt and ln).

   {latitude} + ',' + {longitude}

10. Below the addfieldx instruction, click Add Instruction.

11. In Select Instruction, enter and select convertx.

12. In Field, select String from the drop-down field and enter geolocation into the text field.

13. In Python Expression, enter the following code to convert the geolocation dimension into the correct format.

    {geolocation}.replace('0.0,0.0','')

14. Select the Fail on Error checkbox.

15. Click Next.

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

17. Click Create +.

As a result, the transformation script is created and can be applied to the relevant datastream to create the geolocation dimension.

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 combine latitude and longitude into a single value. Adverity places this single combined value in to the new column (geolocations) in the data extract.

Loading data extracts containing geolocations

To load the data extract that contains the geolocations 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 geolocations. For more information on creating this target field for the Data Mapping, see Mapping source fields.