The Adzerk Developer Hub

Welcome to the Adzerk developer hub. You'll find comprehensive guides and documentation to help you start working with Adzerk as quickly as possible, as well as support if you get stuck. Let's jump right in!

Reserved Keys


Zerkel is bundled with a number of reserved keys that allow for targeting using databases and lookups integrated with Adzerk, such as MaxMind.

These reserved keys do not require key value pairs to be passed into the ad request.
Reserved Keys include targeting by device, location, keywords, userDB, contentDB, userAgent, url, referral url, site, zones, ad types, divName, language, and date/time.

Many Reserved Keys involve knowing the useragent. For Decision API requests, you'll need to grab and pass the ad viewer's useragent in the Adzerk HTTP request. Otherwise, the default will be your server - which won't help with targeting!

All key names beginning with "$" are reserved. If a request contains custom properties beginning with "$", they will be ignored.


For API calls, requires the passing of useragent.

Targets based on characteristics of the device making the ad request. This is particularly useful for mobile targeting to display ads appropriate for each device.

The $device object contains the following properties:

Zerkel Key


Brand (ex: Nokia)


Model (ex: N95)


In addition to Brand and Model, some devices have a marketing name (for ex: BlackBerry 8100 Pearl, Nokia 8800 Scirocco, Samsung M800 Instinct).


Operating system name


Operating system version


Full representation of the version string


Major version number (group of digits before dot) if available. Defaults to 0 if no number represented


Minor version number (group of digits after dot) if available. Defaults to 0 if no number represented


Information about the device browser


Which version of the browser


Screen width in pixels


Screen height in pixels


Image's maximum viewable width in pixels


Image's maximum viewable height in pixels


Screen width in millimeters


Screen height in millimeters


Either "desktop", "phone", or "tablet"

Due to how Apple has chosen to not reveal the device name within the User Agent string, it is not always possible to determine the specific model of an Apple device. We will determine that a device is an iPhone, but we will not always tell you the precise model, resolution, or physical screen size.

In these cases, we fallback to reporting the device as an "iPhone" with the most modest screen capabilities. In other words, we will under-report the resolution and screen size to the original iPhone capabilities.


"iPhone 5S"
"Mozilla/5.0 (iPhone; CPU iPhone OS 7_1 like Mac OS X) AppleWebKit/537.51.2 (KHTML, like Gecko) Mobile/11D167 [FBAN/FBIOS;FBAV/;FBBV/6660503;FBDV/iPhone6,1;FBMD/iPhone;FBSN/iPhone OS;FBSV/7.1;FBSS/2; FBCR/AT&T;FBID/phone;FBLC/en_US;FBOP/5]"
$device.brandName = "Apple"
$device.modelName = "iPhone 5S"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "7.1"
$device.browser = "Safari"
$device.browserVersion = "7.1"
$device.resolutionWidth = 640
$device.resolutionHeight = 1136
$device.maxImageWidth = 320
$device.maxImageHeight = 480
$device.physicalScreenWidth = 50
$device.physicalScreenHeight = 89
$device.formFactor = "phone"

"iPhone 6 Plus"
"Mozilla/5.0 (iPhone; CPU iPhone OS 8_0 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Version/8.0 Mobile/12A366 Safari/600.1.4"
// NOTE: The iPhone 6 Plus cannot be detected precisely via its user agent string,
// so it is reported as an "iPhone" with much smaller resolution and screen size.
$device.brandName = "Apple"
$device.modelName = "iPhone"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "8.0"
$device.browser = "Safari"
$device.browserVersion = "8.0"
$device.resolutionWidth = 640
$device.resolutionHeight = 960
$device.maxImageWidth = 320
$device.maxImageHeight = 480
$device.physicalScreenWidth = 50
$device.physicalScreenHeight = 74
$device.formFactor = "phone"

"iPad 3"
"Mozilla/5.0 (iPad; CPU OS 5_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9B176 Safari/7534.48.3"
$device.brandName = "Apple"
$device.modelName = "iPad"
$device.marketingName = ""
$device.os = "iOS"
$device.osVersion.string = "5.1"
$device.browser = "Safari"
$device.browserVersion = "5.1"
$device.resolutionWidth = 768
$device.resolutionHeight = 1024
$device.maxImageWidth = 768
$device.maxImageHeight = 1024
$device.physicalScreenWidth = 148
$device.physicalScreenHeight = 198
$device.formFactor = "tablet"

"Samsung Galaxy Tab"
"Mozilla/5.0 (Linux; U; Android 4.2.2; nl-nl; GT-P5210 Build/JDQ39) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30"
$device.brandName = "Samsung"
$device.modelName = "GT-P5210"
$device.marketingName = "Galaxy Tab 3 10.1"
$device.os = "Android"
$device.osVersion.string = "4.2"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 800
$device.resolutionHeight = 1280
$device.maxImageWidth = 320
$device.maxImageHeight = 400
$device.physicalScreenWidth = 136
$device.physicalScreenHeight = 218
$device.formFactor = "tablet"

"Amazon Kindle Fire"
"Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_6_3; en-us; Silk/ AppleWebKit/533.16 (KHTML, like Gecko) Version/5.0 Safari/533.16 Silk-Accelerated=true"
// NOTE: This User Agent indicates a Kindle Fire in "desktop mode",
// but we can still identify it as a tablet.
$device.brandName = "Amazon"
$device.modelName = "D01400"
$device.marketingName = "Kindle Fire"
$device.os = "Android"
$device.osVersion.string = "2.3"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 600
$device.resolutionHeight = 1024
$device.maxImageWidth = 600
$device.maxImageHeight = 875
$device.physicalScreenWidth = 90
$device.physicalScreenHeight = 154
$device.formFactor = "tablet"

"HTC Z710 Sensation"
"Mozilla/5.0 (Linux; U; Android 4.0.3; de-ch; HTC Sensation Build/IML74K) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30"
$device.brandName = "HTC"
$device.modelName = "Z710"
$device.marketingName = "Sensation"
$device.os = "Android"
$device.osVersion.string = "4.0"
$device.browser = "Android Webkit"
$device.browserVersion = ""
$device.resolutionWidth = 540
$device.resolutionHeight = 960
$device.maxImageWidth = 360
$device.maxImageHeight = 640
$device.physicalScreenWidth = 54
$device.physicalScreenHeight = 96
$device.formFactor = "phone"

Two common $device queries are used to split traffic between desktop/tablet and phone devices.

To target desktops and tablets:

$device.formFactor = "desktop" OR $device.formFactor = "tablet"

To target mobile:

$device.formFactor = "phone"


For API calls, requires the passing of Keywords.

With $keywords you can target by keywords passed in the request. This can be used even without setting up Keyword Targeting at the flight or ad level.

The reason for using this would be because of the advanced logic you can apply when using Custom Targeting.

For instance, the below example would not be doable with Keyword Targeting, but is with $keywords reserved key:

($keywords contains "tuna") and not ($keywords contains "dolphins")


For API calls, requires the passing of ip.

Targets geographical information about the request, derived from the user's IP address. If no geographical information could be found, all properties within $location will be undefined.

The $location object contains the following properties:

Zerkel Key


Targets a user's IP address. Works best with the like operator: $ip like "74.125.*"


City name


The numeric Nielsen designated market area code (US only)


The two-character country code


Country name






Metro Code (US Only)


Postal Code


The two-character code for the state, region, or province


A two or three-character code for a subregion. Certain countries only

For example, to target a flight to visitors in either Canada or Minnesota:

$location.countryCode = "CA" or ($location.countryCode = "US" and $location.region = "MN")

To prevent a flight from being served to Australia:

NOT ($location.countryName = "Australia")


$location.countryName <> "Australia"

Some countries use subRegions in addition to regions. These are known as "Second-level subdivisions" in the ISO 3166 standard. For example, in the countryCode "GB" (Great Britain), "BKM" (Buckinghamshire) is a second-level subdivision of "ENG" (England). Refer to the individual country you are targeting in the ISO 3166 standard docs to determine whether this country uses subRegions.

Adzerk supports targeting to both IPv4 and IPv6 addresses. However, custom targeting will only match the IP version found on the request.

For example, if you target a flight to an IPv6 address that is a translation of an IPv4 address, we will only target the ad to a request from an IPv6 address, not from the equivalent IPv4 address.


Requires passing of the key value in the user object, as well as UserDB, a feature in the Business or Enterprise plan.

Zerkel Key

$user.custom.[insert custom data interest]


$user.retargetingSegments.[insert advertiserID]


Target to users who have blocked an advertiser, campaign, flight, or creative



Custom Interest

$user.custom.faveFood = "milksteak"


$user.interests CONTAINS "ghouls"


$user.retargetingSegments.b422 = 1

Blocked items

$user.blockedItems.advertisers contains 1234
$user.blockedItems.campaigns contains 1234
$ contains 1234
$user.blockedItems.creatives contains 1234


Requires ContentDB, available in the Business and Enterprise tiers.

ContentDB is a server-side database for storing and targeting contextual metadata. You can target data stored in ContentDB via the below key:

Zerkel Key

$content.custom.[Schema].[The JSON Object Key of the ContentKey]

ContentDB targeting against a Schema/ContentKey

For example, for a music site with the below Schema (Song) and ContentKey Records within it, they would set up the Zerkel query as depicted below.

Schema: Song

Song 1234:
  "title": "Somebody To Love",
  "artist": "Queen",
  "genres": ["classic rock", "electric guitar"]`

Song 4567:
  "title": "Why Can't This Be Love",
  "artist": "Van Halen",
  "genres": ["classic rock", "electric guitar"]`

Target any song with "love" in its title

$ contains "love"

Target only requests that have schema data

$ <> null


For API calls, requires the passing of useragent.

Targets the user agent provided with the ad request. The $userAgent object contains four properties:

Zerkel Key


The actual text of the user agent


Information about the user's web browser


Information about the user's operating system


Information about the user's mobile device, if any

The browser and os properties are themselves objects, with the following properties:



The name of the browser (i.e. Chrome) or operating system (i.e. Mac OS X)


An object containing the segments (major, minor, and patch) of the version number of the browser or OS

Targeting rules can use any or all of these properties. For example, to target people using Windows and a version of Chrome earlier than version 30:

$ = "Windows" and $ contains "Chrome" and $userAgent.browser.version.major < 30

To just target people on a certain mobile device, for example, iPhone:

$ = "iPhone"

The components of a user agent in Zerkel are represented with the following model:

{ text: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.114 Safari/537.36',
  { name: 'Chrome',
      { major: 35,
        minor: 0,
        patch: 1916 } },
  { name: 'Mac OS X',
    version: { major: 10, minor: 9, patch: 2 } },
  device: { name: 'Other' } }


For API calls, requires the sending of url in request.

Targets the URL of the page that makes an ad request. Use with contains to target a full URL or a portion of a URL.

$url contains ""


$url contains "adzerk"

The $url key matches the characters within the contains string against the request URL. For example, you can target a flight to a secure URL only:

$url contains ""

Or you can match against both and by using:

$url contains ""

You can also use regular expressions with $url for advanced URL targeting. For example, this query will target any URL that contains in the domain, including secure sites, URLs with ports, and subdomains:

$url =~ "^https?://([^/:]\.)*foo\.bar\.com([:/].*)?$"

This query will target any of three domains (,,

$url =~ "^https?://([^/:]\.)*(foo\.bar\.com|micha\.rules\.co|micha\.sucks\.co)([:/].*)?$"

Learn more about using regular expressions to match URLs from the IETF and StackOverflow.


For API calls, requires the sending of referrer in request.

Targets of the referrer of the URL that makes an ad request. Use with contains. This is useful for targeting the parent page if the Adzerk request is placed inside of an iframe. To target ads that originate from iframes on

$referralUrl contains ""

The $referralUrl key uses the same matching logic as $url.


For API calls, siteID is already a required field

Targets the name of the Adzerk site (not necessarily the domain that is serving the ads). This object also contains the property id.

$site = "Adzerk"


$ = 99201


For API calls, requires the sending of zoneIDs.

Targets the Adzerk zoneId making the request. This is an array. For more info on Zones, click here.

$zones contains "8675309"


For API calls, requires the sending of adTypes.

Targets the ad types available on the placement making the request. This array can be used to single out a particular ad type, or to target placements that can serve one ad type but not others. Learn more about Ad Types here.

$adTypes contains "5"


For API calls, divname is already a required field.

Targets the div name (DOM identifier) of the placement making the request. This enables placement-level targeting.

$divName = "728_above_the_fold"


For API calls, requires the sending of useragent.

Targets the language set by a user's browser (also known as "locale") to enable language targeting. Use this list of available language codes for targeting, such as:

$acceptLanguage contains "en-us"


Nothing extra needs to be passed in API requests for $datetime targeting.

Target based on date/time information.

The $datetime key is set to the server time, and is defined in GMT. Note that the system treats "12:00 AM - 12:59 AM (or 00:00 - 00:59)" as the first hour, which is represented by "1", which is shown in the chart below.

Zerkel Key


The current day of the week, numeric index (starts on Sunday, range is 1-7)


The current hour, 24-hour format (1-24)


Minutes (0-59)


Seconds (0-59)


Number of seconds since the Unix Epoch



Only on Wednesdays

$datetime.dayofweek = 4

Target for one minute, 15 minutes after every hour

$datetime.minute = 15

Between 8pm and 10 PM (GMT)

$datetime.hour >= 21 and $datetime.hour <= 23

Between 8 PM and 4 AM (GMT)

($datetime.hour >= 21 and $datetime.hour <= 24) or ($datetime.hour >= 1 and $datetime.hour <= 5)


Target based on regulatory data, i.e. GDPR jurisdiction and consent.

Zerkel Key


Is true if the request is GDPR-regulated; i.e. from an European IP address. Is false otherwise.


Is true if the request has GDPR consent. Is false otherwise.

To target EU users who have passed GDPR consent, use:

($regs.gdpr AND $consent.gdpr)

To target EU users who have not passed GDPR consent, use:

($regs.gdpr AND NOT $consent.gdpr)

To target users not subject to EU regulation, use:

not $regs.gdpr


Targets on whether a request originates from a TAG (Trust Accountability Group) known datacenter IP address.

Zerkel Key


Is true if the request originates from a known datacenter.

To target requests from known datacenters:


To target requests not from known datacenters:

not $datacenter

Reserved Keys

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.