How to use Data Keys and Data Key Targets via API

This guide is an overview for implementing Data Keys and Data Key targets via AdButler's API. For details on the endpoints themselves, check our API documentation for Data Keys and Data Key targets.

AdButler’s Data Keys are key-value pairs that offer more ways to target your audience. For example, you can create a key age with type NUMBER to hold age values.

Data Keys don't do anything on their own. They must be used in tandem with Data Key targets, which combine Data Keys with conditional operators and options, such as AND, OR, >, starts-with, and is-after.

Going back to our previous example, you can use the Data Key age to create a Data Key target that lets you serve ads only to audiences of a certain age (=) or age range (>=).

You can also incorporate multiple data key targets into one target. For instance, you can further restrict audiences by both age and gender, or by name or location.

It might help you to read our interface guide on Data Keys so you can see how Data Keys and data key targets are created using AdButler's UI.

Data Key targeting can be used on its own or with other targeting methods to make your target audience as specific as needed.

In this guide, you will learn about:

  1. Creating Data Keys.
  2. Passing Data Keys via GET.
  3. Passing Data Keys via POST.
  4. Creating Data Key targets.
  5. Data Key target operators and options.

How to create Data Keys

To create a Data Key, provide its name and type. name must be a string, while type must be one of the following: STRING, NUMBER, DATE, DATETIME, or TIME.

Example:

{
"name": "age",
"type": "NUMBER"
}

As their names suggest, each key type can hold only certain values, but the Data Key itself is actually a string. For example, in a Data Key target, the value of age is assigned as follows:

{"age" : {">" : "25"}}

How to pass Data Keys via GET

Use the _abdk[] query parameter in your ad request to pass your Data Keys to AdButler.

Example:

https://ads.domain.com/adserve/;ID=171230;size=300x250;setID=373469;type=json;_abdk[bird]=duck;_abdk[bug]=ant;click=CLICK_MACRO_PLACEHOLDER
Query parameters should be added before ;click=CLICK_MACRO_PLACEHOLDER to make sure the request is read correctly. Everything after the ;click= parameter is read as one value. If you do not have a click tracking link, we recommend removing the ;click= parameter. Doing so will also make it easier to add or remove other parameters without affecting your ad's click-throughs.

How to pass Data Keys via POST

You can also pass Data Keys via POST. In this case, you will use the _abdk_json field.

Example:

POST https://ads.domain.com/adserve
{
"ID": 171230,
"size" : "300x250",
"setID": 373469,
"type" : "json",
"_abdk_json" : {
        "bird" : "duck",
        "bug" : "ant"
    }
}

How to create Data Key targets

As stated in the introduction, before creating a Data Key target, you must first create the Data Key(s) that you will reference in the target.

To create a Data Key target, provide its name (optional) and target. The latter is a JSON blob formatted as a Lisp S-expression. This is where you enter comparative values for your Data Keys and add the logic operators and options that will flesh out your targeting criteria.

Let's say you want to target male audiences over the age of 25. You create Data Keys age and gender. You can then write your Data Key target as

["AND",
        {"age" : {">" : "25"}},
        {"gender" : {"=" : "male"}}
    ]

When passing the Data Key target to AdButler, the JSON must be in a string, i.e. they must have escape characters.

{
"name": "Data Key target 1",
"target": "[\"AND\",
        {\"age\" : {\">\" : \"25\"}},
        {\"gender\" : {\"=\" : \"male\"}}
    ],"
}

As shown in the example, a Data Key target has a logical grouping that consists of an array beginning in either AND or OR, followed by a comma-separated list of Data Key comparators.

The names of the Data Keys that you reference in the target must match the names of the Data Keys you created. Otherwise the target will not work. Similarly, ensure that your Data Key's type is compatible with the operator that you wish to use. Check the table of logic operators and options for their compatibilities.

Just like in the AdButler interface, you can also make Data Key targets that consist of multiple logical groupings.

Going back to the previous example, let's say your target can now be male audiences over the age of 25, or audiences over the age of 50 who are either female and own iPhones, or living in the United States. You then create a third Data Key device and a fourth Data Key location. You can then expand your Data Key target as

{
"name": "Data Key target 1",
"target": "[\"OR\",
    [\"AND\",
        {\"age\" : {\">\" : \"25\"}},
        {\"gender\" : {\"=\" : \"male\"}}
    ],
    ["\AND\", 
        {\"age\" : {\">\" : \"50\"}},
        [\"OR\", 
            [\"AND\", 
                {\"gender\" : {\"=\" : \"female\"}},
                {\"device\" : {\"=\" : \"iphone\"}}
            ],
            {\"location\": {\"=\" : \"USA\"}}
        ]
     ]
  ]"
}

Data Key target logic operators and options

Operator
Definition
Compatible type
AND The target audience must meet all requirements within the logical grouping. Logical grouping
OR The target audience meets any of the requirements within the logical grouping. Logical grouping
= is equal to NUMBER, STRING
!= is not equal to NUMBER, STRING
< is less than NUMBER
<= is less than or equal to NUMBER
> is greater than NUMBER
>= is greater than or equal to NUMBER
starts-with conditional characters at the start of the retrieved string STRING
ends-with conditional characters at the end of the retrieved string STRING
contains conditional characters anywhere within the retrieved string STRING
does-not-contain conditional characters should not be in the retrieved string STRING
is-before the retrieved time must come before the retrieved value DATE, TIME, DATETIME
is-after the retrieved time must come after the retrieved value DATE, TIME, DATETIME
is-between the retrieved time must be between the retrieved values DATE, TIME, DATETIME

Can't find what you're looking for?

Send us an email

hello@adbutler.com

Visit the blog

For more ad serving tips, industry news and AdButler insights.