Geographic targeting
Targeting from country down to city and ASN — and how to tell which dimension has no inventory when it fails.
Targeting has two layers: is the syntax valid (checked at the gateway, 400 if not) and does any IP satisfy it (503 if not). Diagnose them separately.
Four targeting dimensions
Coarse to fine:
# Country only
USERNAME-country-US
# Country + state
USERNAME-country-US-state-California
# Country + state + city
USERNAME-country-US-state-California-city-Los%20Angeles
# Pick an ASN (operator targeting; omit state and city while diagnosing)
USERNAME-country-US-asn-AS7922
Country
Two uppercase ASCII letters.
curl -x 'http://USERNAME-country-DE:PASSWORD@GATEWAY_HOST:58971' https://ipinfo.io/json
The gateway validates only the "two uppercase letters" shape and does not check that the code is a real country. So ZZ passes validation but returns 503 when no proxy IP matches. The list of available countries is whatever the console's geography catalogue shows.
State / province
state and region are fully equivalent aliases — either works, but not both.
USERNAME-country-US-state-California # equivalent
USERNAME-country-US-region-California # equivalent
USERNAME-country-US-state-CA-region-California # rejected: duplicate key
Values are matched exactly and case-sensitively. California and california differ, and so do CA and California — which one works depends on how the geography catalogue stores it.
City
USERNAME-country-US-state-California-city-Los%20Angeles
Two easy mistakes:
Spaces must be written %20. City names contain them often.
Hyphens must be written %2D. Otherwise they're read as option separators:
# Wrong: parses as city=Winston + unknown key Salem → whole request rejected
USERNAME-country-US-state-NC-city-Winston-Salem
# Right
USERNAME-country-US-state-NC-city-Winston%2DSalem
City targeting requires country and state too. country + city alone usually returns no matching proxy IP.
ASN
Operator targeting is a single parameter, asn — there is no separate ISP parameter, because an operator is identified by its ASN number.
USERNAME-country-US-asn-7922
USERNAME-country-US-asn-AS7922 # equivalent; the AS prefix is optional and case-insensitive
After stripping the AS prefix it must be a positive integer between 1 and 4294967295.
The proxy generator in the console lets you search this field by operator name — typing Comcast lists the ASN numbers registered to it. What goes into the username is the number (asn-7922), not the name.
Diagnosing a targeting failure
When the syntax is right but no IP comes back, the gateway returns HTTP 503 (SOCKS5 reply 0x01). The X-NextProxy-Error: service_unavailable header and JSON body report temporary unavailability. Remove targeting conditions one at a time to diagnose it.
Work backwards by removing options fine to coarse:
Country only
curl -sx 'http://USERNAME-country-US:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org
Failing here → that country has no inventory at all, or your account isn't entitled to this product or region.
Add the state back
curl -sx 'http://USERNAME-country-US-state-California:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org
Failing here → the state spelling doesn't match the geography catalogue, or that state genuinely has no inventory.
Add the city back
curl -sx 'http://USERNAME-country-US-state-California-city-Los%20Angeles:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org
Failing here → wrong city spelling, a missing escape, or no inventory in that city.
Swap in the ASN last
Specifying asn may return no matching proxy IP, and combining it with state or city may also be unavailable. For this diagnostic step, remove state and city before specifying the ASN:
curl -sx 'http://USERNAME-country-US-asn-7922:PASSWORD@GATEWAY_HOST:58971' https://api.ipify.org
Failing here means that ASN currently has no available proxy IP; consider using city targeting instead.
Targeting granularity varies by product line
| Product line | Supported targeting |
|---|---|
| Dynamic residential | Country / state / city / ASN |
| Static residential | Country (chosen at purchase, fixed afterwards) |
| Datacenter | Country (chosen at purchase, fixed afterwards) |
| Unlimited residential | Determined by the plan; no region parameters at checkout |
Verifying targeting worked
Once you have an IP, cross-check it against an endpoint that reports attribution rather than just confirming the IP changed:
curl -s -x 'http://USERNAME-country-US-state-California-city-Los%20Angeles:PASSWORD@GATEWAY_HOST:58971' \
https://ipinfo.io/json