Data Enrichment API
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.
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.
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:
You can also create segments based on the Enrichment Fields, which can be very useful when grouping URLs in clusters.
On the page detail screen, you will always see the data for the given page:
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 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”
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.
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
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.
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/jsonNote: 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.
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!
