HTTP Request Enrichments

What are HTTP Request Enrichments?

HTTP Request Enrichments allow you to enrich your dataset using any HTTP service. This allows you to build enrichments using any service that Census may not natively support. Similar to AI columns and other enrichments, Census allows you to configure a HTTP request that is unique to each row in your dataset, and map the response back to a column. The enrichment is stored and materialized back in your warehouse.

Example Use Cases

Creating a HTTP Request Enrichment

For this example, we will use MaxMind to enrich website event data with geographic information.

Defining a HTTP Request Connection

1. Login to Census and select a Dataset you want to enrich on the Datasets tab

2. Ensure that your dataset has a Unique ID Column. You can configure this by setting the Type and Property Mappings on the Dataset

3. On the top right corner, navigate to Enrich & Enhance > Enrichments > HTTP Request

4. Create a new HTTP Request Connection, or select an existing connection that you want to use

   1. For MaxMind, we will use their GeoLite API: https://geolite.info/geoip/v2.1/country

   2. You will need to add an Authorization Header in the form Basic <base64 encoding of ACCOUNT_ID:LICENSE KEY>. You can generate a new license key with MaxMind through their accounts portal: https://www.maxmind.com/en/accounts/. See MaxMind's docs on Authorization for more information.

Defining the Request

1. Once you have your HTTP Request Connection selected, you can begin setting up your HTTP request

   1. Name your enrichment

   2. Choose an HTTP method, ex. GET

   3. Configure your endpoint. This could be a constant value, or use Liquid Templates to encode record values in your endpoint. Note that theurl_encode Liquid Filter should be used to ensure that any special characters in your data will be parsed properly to be used in the URL

   4. If your chosen HTTP method supports defining a request body (ex. POST), you can also use Liquid Templates to reference column values for each row.

Defining the Response

1. Define each column of your enrichment by mapping the output names to keys in the returned JSON object. Each output name can be either a:

   1. Top level key of the JSON object

   2. A valid JSONPath pointing to a nested value in the JSON object

{
    "lang": "EN",
    "country": {
        "iso_code": "US",
    }
}

Final Steps

1. Once you are done configuring your request and response, you can go ahead and create your HTTP Column!

Behind the scenes, Census will set up a table in your warehouse to store your enriched data. Census will also create a sync configuration that runs your enrichment and writes it into the created table.