> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abtestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geo targeting

> Country, region, and city, looked up at the edge, cached per session, bounded wait so a slow lookup does not stall the page.

Target visitors by where they are. Three fields, all resolved at the
edge from the visitor's IP.

<Note>
  **Availability.** Geo targeting is on the **Pro plan and above**.
  Free and Starter plans can still target by URL, device, source, and
  custom cookies; they just cannot filter by country, region, or city.
  See [pricing](https://abtestly.com/pricing).
</Note>

## The fields

* **Country**, multi-select from the ISO list.
* **Region**, case-insensitive text match (state, province).
* **City**, case-insensitive text match.

Any combination is fine. Empty means "match every visitor" for that
field.

## How it is resolved

At page load the snippet calls `GET /g` on `api.abtestly.com`. The
worker looks the visitor's IP up in Cloudflare's geo tables and
returns:

```json theme={null}
{ "country": "US", "region": "CA", "city": "San Francisco" }
```

Cached per browser session. Bounded wait of 250 ms, if the lookup
takes longer, the visitor is treated as **unknown country** for that
pageview and geo-dependent rules do not match.

## Fails open

Missing headers, unknown country, timeout, all result in the
geo-dependent rule not matching. The rest of the experiment still
runs; the visitor just is not counted against a geo-scoped audience.

This is a "fails open" policy: an occasional missed exposure is
better than an occasional bad exposure on the wrong audience.

## Where geo lives in the app

* On experiments, under **Who sees it** (Audience).
* On saved Audiences, same picker.

Geo is deliberately not in **Where it runs** (Locations) because
Locations are per-URL and geo is per-visitor.

## Country accuracy

Cloudflare's country data is accurate to the country level for well
over 99 % of real traffic. Region and city are less accurate, VPN
users, mobile carriers, and edge cases can produce region/city
mismatches even when the country is right.

Rule of thumb: rely on country for anything you care about, use
region/city only as an additional filter that you can accept losing
some matches on.

## Latency budget

The 250 ms cap exists so that a slow geo lookup does not stall your
page. In practice the lookup is usually under 10 ms because it runs at the
edge next to the visitor.

If you have geo-dependent audience rules on every experiment, that
250 ms cap can occasionally kick in during Cloudflare incidents.
Nothing breaks; the affected visitors are just not bucketed into
those specific experiments for that pageview.

## Feature flag

Geo lookup can be turned off site-wide (an `ABTESTLY_GEO_ENABLED`
kill-switch). If you do not have geo audience rules on any experiment,
the flag is a no-op. If you have geo everywhere and you specifically
need to zero the geo overhead, ask us.