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, Metro/DMA Code (United States only), or City.

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

Kevel uses IP-based location data to target.

👍

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,
    "City":"Durham",
    "CityGeonameId":4464368,
    "IsExclude":false
  }]
]

📘

Targeting a City

City targeting is matched on the city's CityGeonameId, not the City name, which is used for display. Retrieve the IDs for a region from the List Cities in Region endpoint. A create also requires CountryCode and Region to be present so the city can be resolved and validated. City-level coverage is strongest in the United States and more limited in other countries.

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,
  "City":"Durham",
  "CityGeonameId":4464368,
  "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
List Cities 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 the UI, or to the CustomTargeting field on the Flight, Ad, or Channel in the Management API. 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: