Geolocation Targeting

How to target specific countries and cities with residential proxies

Country and city geolocation targeting comes as standard with all residential data purchases. We support over 195 countries and every major city in the world.

You can generate proxies which are geolocated to specific countries or cities through both our dashboard generator and through syntax generation in your API requests.

Country Targeting

When generating residential proxies, you can specify the country using the ISO country code:

# Generate 5 proxies from the United States
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&list_count=5' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

This will return proxies exclusively from the specified country:

{
  "data": [
    "socks5h://your_user_c_us_s_DDINPY7TQ0781XEO:[e-mail]:8000",
    "socks5h://your_user_c_us_s_XIINPY7TQ0781XEA:[e-mail]:8000",
    "socks5h://your_user_c_us_s_PPINPY7TQ0781XEB:[e-mail]:8000",
    "socks5h://your_user_c_us_s_QQINPY7TQ0781XEC:[e-mail]:8000",
    "socks5h://your_user_c_us_s_RRINPY7TQ0781XED:[e-mail]:8000"
  ],
  "message": "Residential list successfully created."
}

City Targeting

For more precise targeting, you can generate proxies from specific cities:

# Generate 3 proxies from London, UK
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=gb&city_alias=london&list_count=3' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

Response:

{
  "data": [
    "socks5h://your_user_c_gb_city_london_s_DDINPY7TQ0781XEO:[e-mail]:8000",
    "socks5h://your_user_c_gb_city_london_s_XIINPY7TQ0781XEA:[e-mail]:8000",
    "socks5h://your_user_c_gb_city_london_s_PPINPY7TQ0781XEB:[e-mail]:8000"
  ],
  "message": "Residential list successfully created."
}

Notice that the city information is encoded in the proxy string (city_london).

Subdivision Targeting

You can also target specific subdivisions (states, provinces, regions) within countries:

# Generate 3 proxies from California, US
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&subdivision_id=us-ca&list_count=3' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

Finding Available Cities

To discover which cities are available within a country, you can use the city search endpoint:

# List cities in the United Kingdom
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/city/search?country_id=gb&city_is_populous=true' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

Combining Geolocation with Other Filters

For advanced targeting, you can combine geolocation with ISP/ASN targeting:

# Generate 3 proxies from AT&T (ASN 7018) in the US
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/residential/list?country_id=us&asn_id=7018&list_count=3' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'

Dashboard Generation

You can also easily generate geotargeted proxies through our dashboard interface by selecting the desired country and city from the dropdown menus in the residential proxy generator.

For more information on generating residential proxies, see the Generating Residential Proxies guide.