Locations

helodata residential proxies cover 195+ countries with state and city-level targeting in the larger markets. All three geo segments — region, state, city — go into the proxy username.

Country (region)

Always required. Use the lowercase ISO-3166 alpha-2 code as the region value.

helo_s1a2b3c4d5e-type-res-region-{country}

Examples:

Country	Code	Example
United States	us	helo_s1a2b3c4d5e-type-res-region-us
United Kingdom	gb	helo_s1a2b3c4d5e-type-res-region-gb
Germany	de	helo_s1a2b3c4d5e-type-res-region-de
Japan	jp	helo_s1a2b3c4d5e-type-res-region-jp
Brazil	br	helo_s1a2b3c4d5e-type-res-region-br
India	in	helo_s1a2b3c4d5e-type-res-region-in

The full live list is exposed at:

curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/residential/locations

State / province

Optional. Adds finer targeting in countries that expose subdivisions. Use the lowercase ISO-3166-2 suffix (the part after the dash).

Country	State code style	Example
US	2-letter	state-ca, state-ny, state-tx
Canada	2-letter	state-on, state-bc
Australia	2–3 letter	state-nsw, state-vic
Brazil	2-letter	state-sp, state-rj
Germany	2-letter	state-by (Bayern), state-be (Berlin)

helo_s1a2b3c4d5e-type-res-region-us-state-ca

City

Optional, requires state to be specified. City slugs are lowercase, no spaces, no diacritics.

City	Slug
Los Angeles	la
New York	newyork
San Francisco	sf
Toronto	toronto
London	london
Tokyo	tokyo
São Paulo	saopaulo

helo_s1a2b3c4d5e-type-res-region-us-state-ca-city-la

Not every city in every country has enough live IPs to be targetable — if a city has fewer than 50 active exits, the gateway falls back to state-level and emits a warning header X-Helodata-Fallback: city.

Continent / region groups

If you don't care about the specific country but want to stay in a region, use the meta codes:

Meta code	Includes
region-eu	EU member states
region-eea	EEA (EU + Norway, Iceland, Liechtenstein)
region-latam	Mexico, Central & South America
region-mena	Middle East and North Africa
region-apac	Asia-Pacific

These cannot be combined with state or city.

How geo is resolved

1. helodata holds a per-IP geo database refreshed daily from MaxMind + carrier feeds.
2. When a request arrives, the gateway filters live IPs matching your geo segments.
3. From that filtered set, an IP is chosen by load balancer (rotating) or by session key (sticky).
4. The exit IP appears in your response, e.g. X-Helodata-Exit-IP: 198.51.100.42 and X-Helodata-Exit-Geo: us/ca/la.

If your request gets routed to an IP whose live geo turned out to mismatch (e.g. user moved), it counts against the IP location mismatch tolerance.

Coverage at a glance

Coverage	Countries	State-level	City-level
Live IPs	195+	60+	800+

Tier-1 markets (US, UK, DE, FR, JP, KR, BR, AU, CA) have the deepest pools and the broadest city support.