Unify Location Data

This guide explains how to use the Unify Location Data enrichment to transform location data into a standardized format.

Introduction

Use the Unify Location Data enrichment to standardize location values based on your existing location data. It is often the case that location data has to be unified into a standard format in order to be filtered correctly and visualized properly. If your location data is not unified, it could be mistakenly excluded when certain filters are applied to your data.

Use this enrichment to select the column in your data extract that contains the location data and specify how this data is to be transformed. You can also use this enrichment to add ISO codes for regions and countries to your data extract. ISO codes are required in order to create geo-map widgets in the Explore & Present pages.

For example, in your data extract, the location data is in the form of country names, but you need ISO alpha-2 country codes to create a geo-map widget. Use the Unify Location Data enrichment to add a column to your data extract that is populated with the ISO alpha-2 values corresponding to your existing location data.

Concept

Enriching your data means transforming and tailoring the data according to your needs. An enrichment is a set of instructions that you specify for Adverity to transform your data.

When you create an enrichment, you add it to the list of available enrichments in the workspace.

When you assign an enrichment to a datastream, each time data is fetched for the datastream, the data is transformed according to the enrichment. The enrichment only has an effect on datastreams to which you assign the enrichment.

Prerequisites

Before you complete the procedure in this guide, perform all of the following actions:

• Create a datastream. For more information, see Introduction to collecting data.

• Apply the correct Data Mapping for your datastream. For more information, see Introduction to harmonizing data.

• Make sure that the data extract contains location data.

Procedure

To create a Unify Location Data enrichment for a datastream, follow these steps:

1. Select the workspace you work with in Adverity and then, in the platform navigation menu, click Enrichments.

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

3. Click Unify Location Data.

4. (Optional) To assign the enrichment 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 enrichment to them.

5. (Optional) To assign the enrichment 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 enrichment 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 enrichment to them.

6. Click Next.

7. In the Select the geo data to enrich section of the enrichment configuration, fill in the following fields:

   Source column

   In the drop down menu, select the column that contains the location data. This location data is used to create new geo data values.

   Location type

   In the drop down menu, select the type of location data that is in the source column. Choose from one of the following options:

   Country Name

   Select this option if the location data in your source column contains country names, such as United States, Austria, Poland or Kugelmugel. For a full list of compatible country names, see this resource.

   Country code ISO 3166-1 alpha-2

   Select this option if the location data in your source column contains two-digit country codes, such as US, AT or PL. For a full list of compatible two-digit country codes, see this resource.

   Country code ISO 3166-1 alpha-3

   Select this option if the location data in your source column contains three-digit country codes, such as USA, AUT or POL. For a full list of compatible three-digit country codes, see this resource.

   Country code ISO 3166-1 alpha-3 numeric

   Select this option if the location data in your source column contains three-digit country codes, such as 840 for the USA, 040 for Austria or 616 for Poland. For a full list of compatible numerical country codes, see this resource.

   Region code ISO 3166-2

   Select this option if the location data in your source column contains region codes for a country or countries. For example, region codes for US States include US-AL for Alabama or US-HI for Hawaii. For a repository of region codes for a variety of countries, see this resource.

8. On the right side of the page, click Apply.

9. In the Choose location columns to add section of the enrichment configuration, select the type of location you want to add to your data extract. To a new column, select the checkbox of the relevant column name.

   (Optional) Rename the new column that contains the location data. For example, by default, a new column containing the names of a country is called country_name. You can rename this column to a name more suitable to your data extract.

10. On the right side of the page, click Confirm selection.

11. In the Decide how to handle errors section of the enrichment configuration, choose one of the following options:

    Stop and Flag

    If Adverity encounters an error, the enrichment stops and an error message appears on screen.

    Flag and Notify

    If Adverity encounters an error, a warning message is sent to the user that created the enrichment via email. If a value is missing in the data extract, enter a value into the field under this option to populate any missing value entries. This could be used to identify the row in the data extract that caused the enrichment error.

    Ignore

    If Adverity encounters an error, the enrichment ignores the error and continues. If a value is missing in the data extract, enter a value into the field under this option to populate any missing value entries. This could be used to identify the row in the data extract that caused the enrichment error.

12. Click Next.

13. (Optional) In Enrichment name, rename the enrichment.

14. Click Create +.

As a result, you have created a Unify Location Data enrichment. You are then navigated back to the Enrichments overview page and Adverity will apply the enrichment to the datastream automatically. Each time you fetch data with the datastream, the enrichment is applied to the collected data extract. For more information, see Collecting and viewing data.