Data Enrichment API

Plan availability
  • Basic (not available)
  • Standard (not available)
  • Pro (not available)
  • Enterprise (available)

The Data Enrichment API allows you to create custom Enrichment Fields in ContentKing and populate them with any data you need from your end.

You can work with these Enrichment Fields in ContentKing in the same way as the rest of the properties that ContentKing is already monitoring.

Example Use Cases

Sending page metrics data to ContentKing via our Data Enrichment API allows you to filter on these enrichment fields in the Pages Screen and combine them with other on-page properties that ContentKing is already monitoring to create Segments.

You can let your imagination fly when configuring Enrichment Fields. Below you can find just some examples to get you started:

Owner of the Page

Does each of your pages have an owner who is responsible for them? Set up an Enrichment Field Owner, and then you can create new segments for each owner so that everyone knows which pages they need to keep their eye on.

ContentKing - Enrichment Field segment

Revenue per page

Do you have a Revenue metric which shows you the revenue of each individual page? Send this metric directly to ContentKing and configure alerts to be notified about any changes to it.

Find more about the alert here.

ContentKing - Enrichment Field column

Qualified Leads

Counting how many qualified leads each page produces? Why not send this metric to ContentKing and create a segment that groups the highest performing pages together.

Working with the Enrichment Fields in ContentKing

Once Enrichment Fields are added, you can work with the custom metrics across the whole platform, same as with the other page properties and metrics ContentKing is monitoring.

Using Enrichment Fields in Pages screen

Each Enrichment Field has its own dedicated column on the Pages screen which you can use for filtering:

ContentKing - Enrichment Field Pages Screen

You can also create segments based on the Enrichment Fields, which can be very useful when grouping URLs in clusters.

ContentKing - Enrichment Field segment

On the page detail screen, you will always see the data for the given page:

ContentKing - Enrichment Field Details Screen

Using the Enrichment Field data in Alerts

Alerts on Enrichment Fields allow you to be notified about changes of any custom metric that you send to ContentKing.

This alert type is really useful as it allows you to stay on top of any changes that are being made to the metrics you are most interested in. Find more about this alert here.

Data Enrichment API vs Custom Elements

ContentKing has two features which allow you to pull custom metrics to our platform and work with them in the same way as with the rest of the out-of-the-box metrics and properties:

  • Custom Element Extraction
  • Data Enrichment API

The difference between these two features is in the way in which the custom data gets to ContentKing:

  • The Custom Elements are being extracted by ContentKing from the monitored website’s source code or the rendered DOM
  • the Enrichment Fields are populated via the API from your end

Data Enrichment API Terms of Use

By using the Data Enrichment API you agree to the Data Enrichment API Terms of Use.

Setting up the Enrichment Fields

The process of configuring the Enrichment Fields consists of two phases:

  • Configuring the Enrichment Fields in ContentKing
  • Sending the API request to ContentKing

Configuring the Enrichment Fields in ContentKing

The Enrichment Fields in ContentKing can be set up by following these steps:

1. Create Enrichment Fields

To create Enrichment Fields in ContentKing open Settings and click on Enrichment Fields. This will direct you to the Enrichment Fields Editor where you need to tap “Create Enrichment Field”

ContentKing - Enrichment Field creator

2. Choose the Enrichment Field name

Choose the Enrichment Field name that best describes the custom metric you are going to send to ContentKing. For example, Revenue (USD) for the revenue metric or Owner for the owner of the page.

ContentKing - Enrichment Field name

Keep names of your Enrichment Fields consistent across websites so that ContentKing knows they are related.

That way, when you filter on a column for an Enrichment Field on one website and switch to another website that has an Enrichment Field with the same name, the value in the filter will carry over. The same applies for reordering the columns in the Enrichment Field section of Manage columns.

3. Choose the Enrichment Field type

As the next step, choose the format of the Enrichment Field you want to send to ContentKing. You can choose from the following formats:

  • string
  • number
  • boolean
  • date
ContentKing - Enrichment Field type

Important: the Enrichment Field value for all pages that you send in the API request needs to correspond to the field type selected in step 3. Otherwise ContentKing won’t process the API request and will return an error.

4. Retrieve the Enrichment Field ID

Once the Enrichment Field is created you will get an Enrichment Field ID which you need to send with the API request in the next steps.

ContentKing - Enrichment Field id

Sending the API request to ContentKing

As the second phase of configuring Enrichment Fields in ContentKing an API request with the custom metrics and data is sent.

API request headers

The following API request headers need to be sent as part of the API request:

Authorization: token <place-your-enrichment-API-token-here>
Content-Type: application/json

Note: you need to provide the string "token" followed by a space and your actual API token.

The Enrichment API token can be found in the Integration Tokens (opens in a new tab) tab of the Account section.

ContentKing - Enrichment Field token

API Request Body:

Send the custom metrics to ContentKing in the request body. Use the Enrichment Field ID retrieved in step 1.

Example request when sending a string

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id>": "Value1"
            }
        },
        {
             "url": "<url2>",
             "fields": {
                 "<enrichment-field-id>": “Value2”
            }
        }
    ]
}

Example request when sending a boolean

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id>": true
            }
        },
        {
             "url": "<url2>",
             "fields": {
                 "<enrichment-field-id>": false
            }
        }
    ]
}

Example request when sending a date

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id>": "2021-08-10T07:46:44+00:00"
            }
        },
        {
             "url": "<url2>",
             "fields": {
                 "<enrichment-field-id>": "2021-08-10T07:46:44+00:00"
            }
        }
    ]
}

Important: the date needs to be in the ISO 8601 format.

Example request when sending a number

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id>": 1
            }
        },
        {
             "url": "<url2>",
             "fields": {
                 "<enrichment-field-id>": 2
            }
        }
    ]
}

Combining different Enrichment Field types in one request

You can also send multiple Enrichment Fields in one request allowing you to populate data for different Enrichment Fields for the same URL.

Example request when sending a number and a string value

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id-1>":  1
                "<enrichment-field-id-2>": "Value1"
            }
        },
        {
             "url": "<url2>",
             "fields": {
                "<enrichment-field-id-1>":  2
                "<enrichment-field-id-2>": "Value2"
            }
        }
    ]
}

Removing Enrichment Field values

You can also easily remove the Enrichment Field values from the necessary URLs.

Example request when removing values

POST https://api.contentkingapp.com/v1/enrich
{
    "websiteId": "<website-id>",
    "data": [
        {
            "url": "<url1>",
            "fields": {
                "<enrichment-field-id>": null
            }
        },
        {
             "url": "<url2>",
             "fields": {
                 "<enrichment-field-id>": null
            }
        }
    ]
}

Rate limits

Rate limits define the maximum number of requests which can be made in a given time range.

ContentKing’s Data Enrichment API has the following rate limits:

  • 1000 URLs can be sent per request
  • 1 request/second/website

The Data Enrichment API uses rate limits to ensure API request traffic can be handled efficiently.

Need help?

If you need a hand setting up Enrichment Fields or have any questions, don't hesitate to reach out to us and we will be happy to help!