Geo-targeting

Geo-targeting is configured per request by adding flags to the username. No dashboard change, no separate endpoint, every request flows through the same gateway.

Syntax

Flags append to your username with dashes:

customer-USERNAME-country-<code>-region-<name>-city-<name>-asn-<number>

Values are lowercase. Region and city names use underscores for spaces. Country codes are ISO 3166-1 alpha-2.

Available filters

Flag	Value	Example
country	ISO country code	country-us, country-gb, country-de
region	Lowercase region/state slug	region-california, region-new_south_wales
city	Lowercase city slug	city-new_york, city-los_angeles
asn	ASN number	asn-7922 (Comcast), asn-701 (Verizon)
strict	true	strict-true (see Fallback behavior)

Combine flags in any order:

customer-USERNAME-country-us-region-california-city-los_angeles
customer-USERNAME-country-gb-asn-2856
customer-USERNAME-city-berlin

Examples

Country only

curl -x customer-USERNAME-country-de-sid-9f3a2b7c-ttl-600:PASSWORD@p.shifter.io:443 \
  https://ipinfo.io/json

Country + region

curl -x customer-USERNAME-country-us-region-california-sid-9f3a2b7c-ttl-600:PASSWORD@p.shifter.io:443 \
  https://ipinfo.io/json

Country + city

curl -x customer-USERNAME-country-us-city-new_york-sid-9f3a2b7c-ttl-600:PASSWORD@p.shifter.io:443 \
  https://ipinfo.io/json

Country + ASN

curl -x customer-USERNAME-country-us-asn-7922-sid-9f3a2b7c-ttl-600:PASSWORD@p.shifter.io:443 \
  https://ipinfo.io/json

Fallback behavior

By default, if no IPs match your full filter at request time (for example, an obscure city with a momentarily empty pool), the gateway falls back to a broader pool so the request still completes.

Add strict-true to opt out of the fallback and receive HTTP 502 instead. Use strict matching when an exact geo match is more important than the request succeeding:

curl -x customer-USERNAME-country-us-city-new_york-strict-true-sid-9f3a2b7c-ttl-600:PASSWORD@p.shifter.io:443 \
  https://ipinfo.io/json

No filter

Omit all flags to pull from the full global pool:

USERNAME

Every request still rotates to a different IP, just with no geographic constraint.

Next

• Sessions, hold the targeted IP across multiple requests.
• Integrations, plug geo flags into Scrapy, Puppeteer, Playwright.