Geo-Targeting

🚧

Caution

To geo-target accurately with the Decision API, make sure to include the ip field in the Decision request; otherwise, if left blank, the server's IP address 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.

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

👍

Information

We also recommend reading Ad.Product's Geolocation Targeting Guide.

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 the 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.

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

Additionally, you may ping Kevel'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 a geo-targeting endpoint, you will need the required FlightID field; the other fields are optional. Here is an example request:

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

In the Response, you will receive the LocationID, which can then be used to update or delete the geo-targeting in the future.

Seeing Available Locations for Targeting

All available places to target are in the 'Geo Targeting' drop downs.

You may also pull the list automatically by pinging Kevel's list of 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, Kevel will return 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.

📘

Note

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 the Decision API Request. You must also pass ip in the request.

Reserved Key options for location targeting are below.

With Reserved Keys, you receive 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 would write the following Zerkel Query: