## 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](https://dev.kevel.co/docs/geo-location#section-advanced-geo-targeting-with-reserved-keys) and [Zerkel Queries](https://dev.kevel.co/v1.0/docs/zerkel-queries) for more advanced location targeting.

Kevel 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 the time of campaign creation, include the geo-targeting parameters when [Creating a Flight](https://dev.kevel.co/v1.0/reference/flight#create-flight) or in the flight object when [Creating a Campaign](https://dev.kevel.co/v1.0/reference/campaign#create-campaigns).

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

| Name | Description |
| --- | --- |
| `CountryCode`<br>(string) | The 2-3 character string that denotes the country you want to target. |
| `Region`<br>(string) | The 2-3 character string that denotes the region (or state) that you want to target. |
| `MetroCode`<br>(integer) | The 3 digit number that denotes the metropolitan area you want to target. |
| `isExclude`<br>(boolean) | Set to 'false' or `null` if you want to target; `true` if you want to exclude. |

Example:

JSON

```json
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](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#create-geo-targeting)

[Update Geo-Targeting](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#update-geo-targeting)

[Get Geo-Targeting](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#get-geo-targeting)

[Delete Geo-Targeting](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#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:

JSON

```json
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](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#list-geo-codes)

[List Regions in Country](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#list-regions-in-country)

[List Metro Codes in Region](https://dev.kevel.co/v1.0/reference/geo-targeting-endpoints-1#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](https://dev.kevel.co/docs/reserved-keys#section-location), a subset of [Custom Targeting](https://dev.kevel.co/v1.0/docs/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 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: