Targeting Modules
Upgrade Notice
The Targeting API (
targeting_template) has been upgraded as part of the Buzz 2.0 API. We strongly recommend you use the newtargeting-expressionsendpoint. Read more about targeting using the new API.
Buzz uses the concept of strategies to determine valid keys and values for targeting. A list of valid targeting keys and values can be found here: List of Targeting Modules and Keys.
The REST API supports two actions for Modules: A GET request will return the available targeting criteria for a module; and a POST request will validate whether the supplied JSON is valid targeting for the given module.
GET
You can easily get a description of all the supported targeting keys and valid values from a module by calling the API with a GET request and adding /targeting/<module_key> into the request as follows:
curl -X GET "[host]/rest/targeting/<module_key>" -b cookies.txt -d '{}'
#A real example:
curl -X GET "[host]/rest/targeting/geo" -b cookies.txt -d '{}'
#Specifying a key
curl -X GET "[host]/rest/targeting/geo" -b cookies.txt -d '{"key":"country"}'
The results (truncated):
{
"success": true,
"payload": [
{
"name": "country",
"type": "list",
"values": [
{
"country_code_3": "ABW",
"country_code_2": "AW",
"country_name": "Aruba"
},
{
"country_code_3": "AFG",
"country_code_2": "AF",
"country_name": "Afghanistan"
}...
Note, the responses to the GET requests sometimes provide a string list of possible values (e.g. key=country), but in cases without a static list will provide help text (e.g. "key"="zip" will return “Postal code should be passed as a string").
POST
Using the API you can validate a given JSON targeting statement with a targeting module and receive a useful error message if a mistake is detected.
curl -X POST "[host]/rest/targeting/geo" -b cookies.txt -d '{"targeting":[{"geo":[{"include":[{"zip":["11111","11112"]}]}]}]}'
Targeting JSON
Targeting is expressed as a JSON document with a specific syntax. Both the individual Targeting Modules and the Targeting Template module enforce this syntax to assure that any data sent to the ad server is properly validated and formatted.
Example of valid targeting JSON:
{
"geo":
[
{
"include":
{
"country":
[
"USA"
],
"state":
[
"NY",
"NJ",
"MA",
"MI"
]
}
}
],
"time":
[
{
"include_range":
{
"time_of_week":
[
[0,1000],[2000,5000]
]
}
}
],
"site":
[
{
"include":
{
"site_list":
[
"1"
]
}
}
],
"segment":
[
{
"include":
{
"segment":
[
"Women (Age > 25)"
]
}
},
{
"include":
{
"segment":
[
"Women (Age < 40)"
]
}
}
]
}
JSON Structure
The elements of the JSON targeting string is as follows:
| Key | Example value | Description |
|---|---|---|
| module_name | “time”: [{“include”: … }] | A list of sets with the key of a verb, generally include or exclude. The overall statement can include any number of modules, but each module may only appear once |
| verb | “include”: {“key”: … } | Allowable verbs vary by module, but most commonly are “include” and “exclude”. |
| key | “time_of_week”: [{ … }] | Keys are defined in the modules. |
| values | "start": "14:25","end": "19:23" | An array of JSON values corresponding to the key |
Boolean Expressions
Boolean expressions are supported for select targeting modules with support for AND, NOT, OR operators along with parentheses.
For example, the following boolean expression describes targeting a set of segments:
(segment="key-1" AND segment="key-2") OR (segment="key-3" AND segment="key-4") AND NOT segment="key-5"
Validation of boolean expressions will confirm that the expression is valid (e.g. there aren't any un-matched parentheses or non-standard operators) and whether the individual key-value pairs are valid, but will not check to see if the expression is logically consistent.
Updated over 3 years ago