# Geographic targeting

> Filter exits by country or by region.
>
> Web page: https://ports.io/docs/reference/targeting/
> Documentation index: https://ports.io/llms.txt

Use region and country clauses in your proxy username to restrict the exits eligible for a new connection. Filters select from available exits; they do not reserve capacity or guarantee availability in a location.

The same geographic clauses work with HTTP and SOCKS5 proxy authentication. They belong in the routing username, while the full proxy key is the password.

## Target a country

Use a two-letter ISO country code:

```text
v1_rotate_countries_US
```

To allow several countries, separate codes with commas:

```text
v1_rotate_countries_US,GB
```

This permits an exit in either the United States or the United Kingdom. The singular spelling `country` is accepted as an alias for `countries`:

```text
v1_rotate_country_US
```

Use `countries` consistently when generating usernames programmatically.

## Target a region

Use `NA`, `SA`, `AF`, `AS`, or `EU`. Multiple region codes use hyphens:

```text
v1_rotate_regions_NA-EU
```

This permits exits in North America or Europe. See the [region table](https://ports.io/docs/reference/username-reference.md#supported-regions) for names.

Exits in Oceania, such as Australia and New Zealand, have no region code. Target them by country, with `AU` or `NZ`.

## Combine filters

Selections within one list are combined with OR. Different filter clauses are combined with AND. Exclusions are applied to the resulting set.

```text
v1_rotate_regions_NA_countries_US,MX_exclude_MX
```

The exit must match North America and must be in either the US or Mexico, then Mexico is removed. The resulting selection permits only matching US exits.

| Username filters | Eligible geography |
| --- | --- |
| No geographic clauses | Any eligible exit |
| `_countries_US,GB` | US or United Kingdom |
| `_regions_NA-EU` | North America or Europe |
| `_regions_EU_countries_DE,FR` | Europe and either Germany or France |
| `_countries_US,GB_exclude_GB` | US only |
| `_countries_US_exclude_US` | Empty selection |

The last example is syntactically valid but cannot match an exit. Similarly, contradictory region and country requirements can produce an empty selection.

## Apply targeting to a session

The same filter clauses work with sticky and fixed strategies:

```text
v1_sticky_session_checkout-42_countries_US
v1_fixed_session_audit-42_regions_EU_countries_DE,FR
```

Keep the strategy and geographic policy stable for an existing session ID. Create a new session ID when changing its policy. Reusing an active ID with different filters can produce a session policy conflict during connection setup.

## Handle unavailable locations

When no eligible exit matches the request, HTTP proxying returns `502 no_exit_available`; SOCKS5 returns a general-failure CONNECT reply (`0x01`). A valid country code can still have no active exits. See [Troubleshooting](https://ports.io/docs/reference/troubleshooting.md) for protocol-specific errors.

Review contradictory clauses first, then consider a broader selection appropriate to your application. Do not silently broaden geography when your application requires a specific location.

The username grammar currently has no city, state, postal-code, ASN, or carrier selector. A region or country filter refers to the exit's location metadata, not the destination website's location.