Residential Targeting: Country, City and ASN Segments

The username segments that pin a residential exit to a country, state, city or network, why an unservable location is refused, and how to verify the exit.

On the residential gateway, location is declared per request inside the username. Append hyphen-separated segments to your credential and the gateway restricts your exit to the matching part of the pool:

curl -x "http://USERNAME-country-us-city-losangeles:PASSWORD@gw-residential.node4.io:8082" https://ipinfo.io/json

There are five segments: country, state, city, asn and session. The password never changes, the endpoint is always the fixed gateway hostname, and SOCKS5 works the same way on port 1082 (see SOCKS5 setup). Two requests in the same second can exit from two different countries.

Segment reference

USERNAME                                  # untargeted: any available exit
USERNAME-country-us                       # a United States exit
USERNAME-country-us-state-tx              # Texas
USERNAME-country-us-city-losangeles       # Los Angeles
USERNAME-country-de-asn-3320              # a specific German network operator
USERNAME-country-fr-session-run5col       # one French exit, held across requests

Segment	Format	Example
`country`	ISO 3166-1 alpha-2, two letters (the United Kingdom is `gb`; no three-letter codes)	`-country-de`
`state`	two or three letters or digits naming a subdivision, most usefully a US state abbreviation	`-country-us-state-wa`
`city`	lowercase letters and digits only, up to 64 characters, with spaces, accents and punctuation removed	`-city-saopaulo`, `-city-stlouis`
`asn`	the operator's autonomous system number as bare digits, no `AS` prefix, no leading zeros	`-asn-7922`
`session`	letters and digits you invent, up to 32 characters; pins the chosen exit for later requests	`-session-task81f3`

Structural rules, enforced when the gateway parses the username:

Segments are alternating keys and values joined by single hyphens. Every key needs a value: a trailing -city- or a doubled hyphen leaves an empty slot and the whole username is rejected.
The keys are exactly the five words above. Casing is forgiven on the key, but lowercase everything.
Each key may appear at most once. -country-us-country-de is rejected as a duplicate.
Order does not matter. -session-x-country-us and -country-us-session-x mean the same thing.
A hyphen inside a city name is read as a segment boundary, so flatten city names before use.

ASN targeting is granted on residential plans by default alongside country, city and session. Targeting is an entitlement, so if an ASN request returns an entitlement error, that plan has been scoped more narrowly and support can say to what.

How segments combine

Every location segment is a filter, and filters intersect: -country-us-city-losangeles requires an exit that satisfies both, and each segment you add can only shrink the candidate set. There is no precedence. -country-de-city-losangeles has an empty intersection and is refused, not resolved in favor of either value. Always pair city with its country, because city names are not globally unique.

session does not narrow location; it pins one member of the eligible set across requests. Lifetimes, worker binding and expiry are covered in sticky vs rotating sessions. If you change the location segments between requests, mint a new session id as well.

Refused, never redirected

Ask for a location the pool cannot serve (a contradictory combination, an unsupported region, or a city with no exits online at that moment) and the request fails with an error. The gateway does not substitute the nearest alternative, because a silent substitution would hand you well-formed, plausible and wrong data with no marker anywhere to say so. An explicit refusal costs one visible failed request at the moment the problem exists.

Residential availability changes through the day. Exits are consumer devices that join and leave, so a smaller city that served you at noon may have nothing online at four in the morning local time. Read a refusal as "not right now". If the task tolerates it, widen in your own code (city, then state, then country) and record which level each piece of data was collected at.

The targeting builder on the dashboard's Proxies page is generated from a coverage snapshot, so it only offers locations expected to have exits. A hand-typed username can express any syntactically valid location, including ones that will be refused; when a hand-written city keeps failing, check whether the builder offers it. The same snapshot is published as a page per country, United States, United Kingdom, Germany, France, Brazil and India among the larger markets, each listing the cities it can target and the -city- codes for them; the full set is linked from the residential proxies page.

Diagnosing a malformed segment

A targeting mistake surfaces as an authentication failure, because the gateway rejects the whole username. If a credential authenticates bare but fails with segments attached, the segments are the suspect. Causes in the order they occur:

A typo'd key. -cuntry-us is refused rather than ignored, so a typo cannot silently hand you untargeted exits.
A key without a value, usually a trailing or doubled hyphen from string concatenation.
A malformed value: a three-letter country code, a city with an uppercase letter or separator, an AS prefix on the ASN, a session id over 32 characters.
A duplicate key, typically code appending targeting to a username that already had some.

Start from the bare credential and confirm it authenticates; if it does not, this is not a targeting problem and the 407 guide applies. Then add segments back one pair at a time; the first pair that breaks the request is the answer. If you build usernames programmatically, lowercase the city and strip every non-alphanumeric character before concatenating.

Verifying the exit

Ask a geolocation service what it sees:

curl -x "http://USERNAME-country-de-city-frankfurt:PASSWORD@gw-residential.node4.io:8082" https://ipinfo.io/json

The response reports the address with the country, region and city that service attributes to it. Two caveats. IP geolocation is a set of competing commercial databases, not one ground truth: country-level attribution is dependable, city-level attributions disagree between databases routinely, and the database your target consults may not be the one you checked. A wrong country on a targeted request is worth a support ticket; a city attributed to the neighboring suburb is ordinary noise. And verify at the start of a run and periodically during it; for datasets where location is part of the data, log the verified exit alongside each batch.

A targeted exit places your request on a network in that location. It does not by itself supply a local account, delivery address, payment method or language preference; the target reads those from other signals, so treat a local IP as one input to a localization test rather than the whole of it.

Where this fits

Country, state and city targeting ride on the residential plans, which are metered by bandwidth; prices are on the pricing page. If your workload also has a bulk half that does not care where it exits, untargeted rotation is usually the better fit for that portion; how IP rotation works covers choosing between the mechanisms.