Geo-targeting (country pinning)

How it works

By default the residential pool rotates exit IPs across every country it covers. To pin a country, attach a country tag to the proxy username when you connect; the gateway parses it and routes you out of an exit in that country.

The credentials in your dashboard stay the same — the country tag is added on-the-fly to the username at connect time. You can switch countries between requests just by changing the tag; nothing has to be reissued.

Username syntax

Append __cr.<iso2> to the username, lowercase. The host, port, and password do not change.

Default (rotates worldwide):
  USERNAME:[email protected]:823

Pinned to United States:
  USERNAME__cr.us:[email protected]:823

Pinned to Germany:
  USERNAME__cr.de:[email protected]:823

Country codes are ISO-3166-1 alpha-2 in lowercase — us, de, fr, gb, br, jp, etc. The full list of supported codes is available from the country picker in your order page.

Examples

The same change applies in every language. Only the username differs.

# Country: United States
curl -x http://USERNAME__cr.us:[email protected]:823 \
     https://api.ipify.org

# Country: Germany
curl -x http://USERNAME__cr.de:[email protected]:823 \
     https://api.ipify.org

import requests

# Pin Brazil
proxy = "http://USERNAME__cr.br:[email protected]:823"
r = requests.get(
    "https://api.ipify.org",
    proxies={"http": proxy, "https": proxy},
    timeout=15,
)
print(r.text)

import { HttpsProxyAgent } from "https-proxy-agent";
import fetch from "node-fetch";

// Pin Japan
const agent = new HttpsProxyAgent(
  "http://USERNAME__cr.jp:[email protected]:823"
);
const r = await fetch("https://api.ipify.org", { agent });
console.log(await r.text());

Picking from the dashboard

On any fulfilled order the Credentials card has a Country selector above the format tabs. Pick a country and every snippet — host:port, URL, curl, Python, Node, Playwright — rebuilds with the right username. Click Copy and paste into your client.

Clear the country (or leave it as “Any”) to go back to worldwide rotation.

Multiple countries

You can include several countries in one connection — the gateway picks any exit from the union of the listed countries on each request. Separate codes with a comma:

# Rotate across NL, DE, FR
curl -x http://USERNAME__cr.nl,de,fr:[email protected]:823 \
     https://api.ipify.org

The dashboard picker is single-country for now; if you need a multi-country pool, build the username manually using the rule above.

How rotation behaves

• Each request gets a fresh exit IP from the country you specified. If you want the same IP across multiple requests (sticky sessions), reach out — that's a separate feature.
• The country pool is large but not infinite. Heavy parallel use of a small country may collide on the same IP — diversify across countries if your target rate-limits per-IP.
• Switching country between requests is free — the credentials stay the same, only the username tag changes.

Caveats

• Codes are case-sensitive lowercase. US will be rejected — use us.
• The double underscore __ between username and tag is required. _cr.us or -cr.us won't parse.
• Geo-targeting works on the residential pool. Mobile and datacenter pools have different (smaller) coverage; if you need country pinning on those, contact us first.
• State, city, ASN, and ZIP-level targeting are available on request — they're billed at a higher rate so we don't enable them by default. Email support if you need finer granularity.