Geo Targeting

List the geo targets supported by the rotating proxy network. Each entry carries a suffix field — append it to your proxy username to route traffic through that location (see Username grammar).

Results are cached and shared across the network, so these endpoints are safe to call frequently.

List Countries

Returns the countries available for targeting.

Endpoint

GET /api/v2/rotating-proxies/geo/countries/

Query Parameters

Parameter	Type	Required	Description
name	string	No	Case-insensitive filter by country name

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v2/rotating-proxies/geo/countries/' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  { "code": "US", "name": "United States", "suffix": "us" },
  { "code": "DE", "name": "Germany", "suffix": "de" }
]

Response Fields

Field	Type	Description
code	string	ISO 3166-1 alpha-2 country code
name	string	Human-readable country name
suffix	string	Username suffix that targets this country

List Regions

Returns the regions (states/provinces) of a country.

Endpoint

GET /api/v2/rotating-proxies/geo/regions/

Query Parameters

Parameter	Type	Required	Description
country_code	string	Yes	Country code from GET /geo/countries/
name	string	No	Case-insensitive filter by region name

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v2/rotating-proxies/geo/regions/?country_code=US' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  { "country_code": "US", "code": 5, "name": "California", "suffix": "us-california" },
  { "country_code": "US", "code": 12, "name": "Texas", "suffix": "us-texas" }
]

List Cities

Returns the cities of a country, optionally narrowed to a region.

Endpoint

GET /api/v2/rotating-proxies/geo/cities/

Query Parameters

Parameter	Type	Required	Description
country_code	string	Yes	Country code from GET /geo/countries/
region_code	integer	No	Region code from GET /geo/regions/
name	string	No	Case-insensitive filter by city name

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v2/rotating-proxies/geo/cities/?country_code=US&region_code=5' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  { "country_code": "US", "region_code": 5, "name": "Los Angeles", "suffix": "us-losangeles" }
]

List ZIP Codes

Returns ZIP/postal codes for a country, optionally narrowed to a city.

Endpoint

GET /api/v2/rotating-proxies/geo/zips/

Query Parameters

Parameter	Type	Required	Description
country_code	string	Yes	Country code from GET /geo/countries/
city_name	string	No	Filter by city name
name	string	No	Filter by ZIP value

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v2/rotating-proxies/geo/zips/?country_code=US&city_name=Los%20Angeles' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  { "country_code": "US", "city_name": "Los Angeles", "zip": "90001", "suffix": "us-90001" }
]

List ISPs

Returns ISP providers for a country, optionally narrowed to a city.

Endpoint

GET /api/v2/rotating-proxies/geo/isps/

Query Parameters

Parameter	Type	Required	Description
country_code	string	Yes	Country code from GET /geo/countries/
city_name	string	No	Filter by city name
name	string	No	Filter by ISP name

Request

curl -X 'GET' \
  'https://app.cyberyozh.com/api/v2/rotating-proxies/geo/isps/?country_code=US' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your_api_key_here'

Response

[
  { "name": "Comcast Cable", "suffix": "isp-comcast" }
]

Error Responses

Missing Country Code (400)

Returned by regions, cities, zips and isps when country_code is absent.

{
  "detail": "country_code query parameter is required."
}

Gateway Unavailable (502)

{
  "detail": "Geo service unavailable: upstream timeout"
}

Notes

• suffix values are defined by the proxy provider — always read them from these endpoints rather than hard-coding.
• Combine geo suffixes in the order country-region-city-zip-isp when building a username.