Гео-таргетинг

Получите список гео-таргетов, поддерживаемых сетью ротационных прокси. Каждая запись содержит поле suffix — добавьте его к имени пользователя прокси, чтобы направить трафик через эту локацию (см. Грамматика имени пользователя).

Результаты кэшируются и общие для всей сети, поэтому эти endpoint'ы можно безопасно вызывать часто.

Список стран

Возвращает страны, доступные для таргетинга.

Endpoint

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

Параметры запроса

Параметр	Тип	Обязательный	Описание
name	string	Нет	Фильтр по названию страны без учета регистра

Запрос

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'

Ответ

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

Поля ответа

Поле	Тип	Описание
code	string	Код страны ISO 3166-1 alpha-2
name	string	Читаемое название страны
suffix	string	Суффикс имени пользователя для таргетинга на эту страну

Список регионов

Возвращает регионы (штаты/области) страны.

Endpoint

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

Параметры запроса

Параметр	Тип	Обязательный	Описание
country_code	string	Да	Код страны из GET /geo/countries/
name	string	Нет	Фильтр по названию региона без учета регистра

Запрос

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'

Ответ

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

Список городов

Возвращает города страны, опционально ограниченные регионом.

Endpoint

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

Параметры запроса

Параметр	Тип	Обязательный	Описание
country_code	string	Да	Код страны из GET /geo/countries/
region_code	integer	Нет	Код региона из GET /geo/regions/
name	string	Нет	Фильтр по названию города без учета регистра

Запрос

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'

Ответ

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

Список ZIP-кодов

Возвращает ZIP/почтовые коды страны, опционально ограниченные городом.

Endpoint

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

Параметры запроса

Параметр	Тип	Обязательный	Описание
country_code	string	Да	Код страны из GET /geo/countries/
city_name	string	Нет	Фильтр по названию города
name	string	Нет	Фильтр по значению ZIP

Запрос

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'

Ответ

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

Список ISP-провайдеров

Возвращает ISP-провайдеров страны, опционально ограниченных городом.

Endpoint

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

Параметры запроса

Параметр	Тип	Обязательный	Описание
country_code	string	Да	Код страны из GET /geo/countries/
city_name	string	Нет	Фильтр по названию города
name	string	Нет	Фильтр по названию ISP

Запрос

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'

Ответ

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

Ответы с ошибками

Отсутствует код страны (400)

Возвращается endpoint'ами regions, cities, zips и isps, когда отсутствует country_code.

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

Шлюз недоступен (502)

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

Примечания

• Значения suffix определяются провайдером прокси — всегда читайте их из этих endpoint'ов, а не задавайте жестко.
• Комбинируйте гео-суффиксы в порядке country-region-city-zip-isp при построении имени пользователя.