Примеры ProxyShard API

Готовые рецепты на Python для пользовательского API ProxyShard.

Это ответы на самые частые вопросы клиентов — например:

«Как через API запросить 5 residential-прокси в стране X?»

Документация API · Сайт · Issues

🇺🇸 English version: proxyshard-api-examples

---

Что внутри

Скрипт	Что делает
01_check_account.py	Проверка токена (GET /user/api/me)
02_list_residential_subusers.py	Список residential суб-юзеров и их трафика
03_browse_residential_locations.py	Страны, регионы и города для таргетинга
04_generate_residential_proxies.py	Главный рецепт — генерация N прокси с таргетингом
05_test_residential_proxy.py	Health-check сгенерированной прокси через ipapi.co
06_resolve_relay_ipv4.py	Получить актуальный IPv4 relay-хоста (вместо домена)
07_list_dc_isp_active_proxies.py	Datacenter / ISP — список активных прокси на заказе
08_check_order_status.py	Datacenter / ISP — статус заказа, срок, аддоны (p0f-слоты)
09_test_dc_isp_proxy.py	Datacenter / ISP — health-check всех прокси на заказе

Общая логика лежит в proxyshard.py: маленький ProxyshardClient и билдер username для residential.

---

Как устроены URL residential-прокси

В API нет эндпоинта-генератора. Это первое, на чём спотыкаются новые пользователи. Строка прокси собирается на стороне клиента. Формат:

scheme://USERNAME:PASSWORD@HOST:PORT

Пример с реальными значениями:

http://plan-premium-country-de-region-berlin-sid-abc12345:eu5ymcyjcxmxsmc9@relay-eu.proxyshard.com:8080

Разбор по частям:

Часть	Пример значения	Откуда
scheme	http (порт 8080) или socks5 (порт 1080)
USERNAME — таргетинг	plan-premium-country-de-region-berlin-sid-abc12345	Собирается на стороне клиента, см. ниже
PASSWORD	eu5ymcyjcxmxsmc9	proxy_password суб-юзера из /user/api/proxies/sub-users
HOST	relay-eu.proxyshard.com	Один из relay-eu / relay-ua / relay-ru — бери ближайший географически
PORT	8080 (HTTP) или 1080 (SOCKS5)

Сегменты USERNAME:

Сегмент	Обязательно	Заметки
plan-<тип>	да	plan-premium для Premium Residential, plan-limited для Standart Residential
country-<код>	да	ISO 2-буквенный код из /user/api/proxies/countries (например de). any — случайная страна
region-<код>	опционально	Из /user/api/proxies/regions
city-<код>	опционально	Из /user/api/proxies/cities
sid-<случайный>	опционально	Sticky-session id. Тот же sid → тот же IP. Новый sid → новый IP
ttl-<секунды>	опционально	Время жизни sticky-сессии в секундах

Сборку делает proxyshard.py::build_residential_username(). Все примеры используют его.

---

Datacenter и ISP прокси

Здесь всё устроено по-другому. Дашборд выдаёт конкретные выделенные IP в момент покупки, ты забираешь их через GET /user/api/proxies/active?order_id=.... Никакой сборки строки на клиенте.

Поток работы:

1. 08_check_order_status.py — посмотреть активные заказы, выбрать id заказа Datacenter или ISP.
2. Положить id в .env как PROXYSHARD_ORDER_ID=....
3. 07_list_dc_isp_active_proxies.py — забрать строки прокси.
4. 09_test_dc_isp_proxy.py — проверить, что каждая прокси работает и страна совпадает.

Если DC/ISP прокси не работает, чаще всего целевой сайт заблокировал IP или прокси на техобслуживании. Попробуй другой IP на том же заказе; если столкнулся с проблемами — напиши нам в live chat, поможем разобраться.

---

Где взять API-токен

1. Заходишь в dashboard.proxyshard.com.
2. В левом нижнем углу клик по селектору аватара (1), затем Settings (2).
3. В верхних вкладках выбираешь API (3), копируешь токен кнопкой Copy (4) или ротируешь через Change API Key.

Прямая ссылка: https://dashboard.proxyshard.com/en/profile?tab=api-key

Токен — это JWT-подобная строка, начинается с eyJ.... Положи в локальный .env:

cp .env.example .env
# открой .env и вставь токен

PROXYSHARD_TOKEN также подхватывается из обычной env-переменной, если не хочешь файл.

Токен даёт полный доступ к аккаунту. Обращайся с ним как с паролем — никогда не коммить в git. Включённый .gitignore исключает .env.

---

Установка

git clone https://github.com/ProxyShard/proxyshard-api-examples-ru.git
cd proxyshard-api-examples-ru

python -m venv .venv
. .venv/bin/activate         # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# вставь PROXYSHARD_TOKEN в .env

python 01_check_account.py

Если 01_check_account.py распечатал email и баланс — токен рабочий. Можно идти по остальным примерам.

Поддерживается Python 3.9+.

---

Полезные паттерны

Sticky-сессия vs ротация IP

# Тот же sid → тот же выходной IP между запросами
build_residential_username("premium", country="de", sid="my-stable-session")

# Ротация: новый IP на каждый запрос
build_residential_username("premium", country="de", sticky=False)

Время жизни sticky-сессии: максимум 1 день. Сессия может закончиться раньше — residential выходят через реальные домашние устройства. Если устройство ушло из пула (выключилось, сменило сеть, юзер отозвал доступ к раздаче), IP сменится при следующем запросе. Считай sticky best-effort, а не гарантией.

Случайная страна (балансировка по всему пулу)

build_residential_username("premium", country="any")

IP вместо домена

Если в твоей среде ненадёжный DNS-резолвер или хочется не платить за DNS-резолв на каждом запросе — резолви один раз и используй IP:

import socket
ip = socket.gethostbyname("relay-eu.proxyshard.com")
proxy_url = f"http://{username}:{password}@{ip}:8080"

⚠️ IP-адреса relay могут меняться. Не хардкодь их насовсем. Перерезолви хотя бы раз в час или по ошибке соединения. См. 06_resolve_relay_ipv4.py.

Подключение через requests

proxies = {"http": proxy_url, "https": proxy_url}
requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=15)

SOCKS5 с requests

pip install "requests[socks]"

proxy_url = build_proxy_url(username, password, scheme="socks5")  # порт 1080

---

Если residential-прокси не работают

Если 05_test_residential_proxy.py упал или прокси отдаёт не ту страну:

1. Sticky-сессия устарела. Устройство ушло из пула. Сгенерируй новый sid и повтори — relay направит через другое устройство.
2. Закончился трафик. Проверь через 02_list_residential_subusers.py — если data_spent близко к data, пополни лимит суб-юзера в дашборде или через API.
3. Слишком узкий таргетинг. Чаще всего проблема не в стране, а в регионе, и ещё чаще — в мелком городе, где сейчас мало свободных IP. Убери city или region из username либо возьми соседнюю локацию. Под мелкие города Premium Residential обычно покрывает лучше, чем Standart — если нужен конкретный город, бери премы.
4. Ничего не помогло? Напиши нам в live chat, поможем разобраться.

---

Ссылки

• Документация API: https://docs.proxyshard.com/polzovatelskoe-api/general
• Residential API: https://docs.proxyshard.com/polzovatelskoe-api/residential-proxies
• Datacenter и ISP API: https://docs.proxyshard.com/polzovatelskoe-api/datacenter-and-isp-proxies
• Модели данных: https://docs.proxyshard.com/polzovatelskoe-api/models
• По бизнесу: business@proxyshard.com

---

Лицензия

MIT