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!

Geo-Targeting

To geo-target accurately with the Decision API, make sure to include the ip field in the Decision request. Otherwise, if left blank, the IP of the server will be used.

Overview

Geo-targeting enables you to target users based on their current location.

At the flight level, you can target or exclude by Country, Region, or Metro/DMA Code (the latter for the United States only).

You can also use Reserved Keys and Zerkel Queries for more advanced location targeting.

Adzerk uses MaxMind to pull location data and targets by IP.

Enabling via the UI

To target a flight to a geographical area:

  1. Click Geo-Targeting from the Targeting menu on the left.
  2. Decide to Include or Exclude
  3. Select Country
  4. Optional: Region and Metro/DMA Code (US only)
  5. Click Add
  6. Do again for additional inclusions/exclusions
  7. Click Save This Flight at bottom

Enabling Geo-Targeting with API

To add geo-targeting at time of campaign creation, include the geo-targeting parameters when Creating a Flight or in the flight object when Creating a Campaign.

You'll want to add the follow properties wrapped in a geotargeting object within the flights object.

Name
Description

CountryCode
(string)

The 2-3 character string that denotes the country you want to target

Region
(string)

The 2-3 character string that denotes the region (or state) that you want to target

MetroCode
(integer)

The 3 digit number that denotes the metropolitan area you want to target

isExclude
(boolean)

Set to 'false' or null if you want to target; true if you want to exclude

Example:

flight={
  "CampaignId":1234,
  "PriorityId":1325,
  "Name":"Test",
  "StartDateISO":"2017-05-01T00:00:00.00.0000000",
  "GoalType": 1,
  "GeoTargeting":[{
    "CountryCode":"US",
    "Region":"NC",
    "MetroCode":560,
    "IsExclude":false
  }]
]

Updating Geo-Targeting with API

You can additionally ping Adzerk's Geo-Targeting endpoints to get, create, update, or delete a flight(s) geo-targeting.

Create Geo-Targeting
Update Geo-Targeting
Get Geo-Targeting
Delete Geo-Targeting

For creating with Geo-Targeting Endpoint, you'll need the required FlightID field; the other fields are optional. Here's an example request:

geotargeting={
  "FlightId": 12345,
  "CountryCode":"US",
  "Region":"NC",
  "MetroCode":560,
  "IsExclude":true
}

In the Response, you'll get the LocationID, which can be used to update or delete the geo-targeting in the future.

Seeing Available Locations for Targeting

In the UI, if you navigate to the 'Locations' section, you can look through the drop-down for a full list.

You can also pull the list automatically by pinging our List Geo-Targeting endpoints. This will return a ~400 KB JSON object.

List Countries
List Regions in Country
List Metro Codes in Region

Geo-Targeting Behavior

Because regions can overlap, geo-targeting uses a set of rules to prevent conflicts. If you attempt to add geo-targeting with conflicting regions, we'll give an error message.

The following settings will not be saved:

  • You cannot exclude a country but include its regions (e.g. North Carolina but not United States).
  • You cannot exclude a country but include its metros (e.g. San Francisco but not United States).
  • You cannot exclude a region but include its metros (e.g. Greensboro/Winston-Salem but not North Carolina).
  • You cannot include and exclude the same country/region/metro.
  • You cannot include a multi-region metro (like New York City) but exclude all its regions (New Jersey, New York, and Connecticut).
  • You cannot include a region and exclude all its metros.

Advanced Geo-Targeting with Reserved Keys

Reserved Keys, a subset of Custom Targeting, offer more flexibility when setting up geo-targeting.

With Reserved Keys, you do NOT need to add geo-targeting at the flight level. You DO have to add a Zerkel Query to the Custom Targeting section of UI or to CustomTargeting parameter of Decision API Request. You also have to pass ip in the request.

Reserved Key options for location targeting are below.

With Reserved Keys you get more options to choose from - including latitude and longitude - as well as having the ability to use more operators. For instance, if you want to target by a specific postal code (zip code), you'd write this Zerkel Query:

Geo-Targeting