nLevel - Прокси API
nLevel - Прокси API предоставляет простой и удобный способ для автоматизированного получения списков публичных прокси. Используйте его для интеграции в ваши приложения и скрипты.
Получение списка прокси
Для получения доступа к прокси используйте следующий HTTP GET запрос:
format=text — строки в формате IP:PORT (при нескольких типах — IP:PORT|TYPE), по одной на каждую прокси.
format=json — структурированный ответ с полями message и proxies, на которые уже применены все фильтры.
Проверка состояния ключа
Чтобы проверить ключ, не получая список прокси, выполните код.
Активный ключ возвращает ответ следующего вида:
activeпоказывает, действует ли подписка;remaining_secondsсодержит точное оставшееся время в секундах;expires_atсодержит время окончания подписки в UTC.
У ещё не активированного или отключённого ключа оба поля времени равны null. У ключа с истёкшей подпиской remaining_seconds равен 0, а expires_at сохраняет фактическое время окончания.
Этот запрос только читает состояние. Он не активирует ключ, не продлевает подписку и не создаёт или обновляет запись активной сети.
Продление и несколько ключей
Новый ключ, активированный в Private Keeper для того же профиля, продлевает текущую подписку. Если подписка ещё действует, дни нового ключа добавляются к её дате окончания; если срок уже истёк, новый период начинается с момента активации.
После продления предыдущий и новый ключи остаются рабочими. Оба можно передавать в /v2/proxylist.txt и /v2/proxy-status.json, и оба показывают одну дату окончания подписки. Повторная активация уже использованного этим же профилем ключа безопасна, но второй раз дни не начисляет.
Лимит активных сетей и их 24-часовые записи учитываются отдельно для каждого ключа, даже когда несколько ключей принадлежат одной подписке.
Параметры запроса
Для настройки вашего запроса используйте следующую таблицу параметров:
| Параметр | Статус | Описание и примеры |
|---|---|---|
key | Обязательный | Ваш уникальный ключ доступа к API nLevel - Прокси. Пример: key=pk_xxxxxxxxx. |
type | Обязательный | Один или несколько типов прокси через запятую. Пример: type=http,socks5. |
format | Необязательный | Управляет форматом ответа. Значение по умолчанию — text. Укажите format=json, чтобы получить объект с полями message и proxies. |
filter | Множественный | Фильтрация результата по схеме поле:значение. Допускается несколько параметров filter в одном запросе. Примеры: filter=geo.country:DE, filter=responseTimeMs:250, filter=geo.city:*. |
Параметр filter можно указывать несколько раз. Фильтрация выполняется как для текстового, так и для JSON-ответа, поэтому итоговый список всегда соответствует заданным условиям. Используйте точечную нотацию для вложенных полей (например, filter=geo.city:Berlin), а значение * проверяет наличие непустого значения.
Ограничение активных сетей
Получение списка прокси учитывает сеть, из которой выполнен запрос. По умолчанию один ключ может одновременно использоваться не более чем из трёх активных сетей:
- IPv4-адреса с одинаковыми первыми тремя октетами считаются одной сетью
/24; - IPv6-адреса с одинаковыми первыми 64 битами считаются одной сетью
/64.
Первый успешный запрос списка создаёт запись этой сети. Каждый следующий успешный запрос списка из той же сети обновляет её время активности ещё на 24 часа. Это не меняет срок подписки и не продлевает ключ. Если из сети не запрашивали список 24 часа, её запись освобождается и место может занять другая сеть.
Запрос /v2/proxy-status.json не учитывает сеть и не обновляет её время активности.
Доступные типы прокси
Вы можете запрашивать следующие типы прокси:
| Тип | Описание |
|---|---|
HTTP | Подходят для большинства задач веб-серфинга и работают по протоколу HTTP. |
HTTPS | Предоставляют шифрование трафика между клиентом и прокси-сервером. |
SOCKS4 | Работают на более низком уровне, чем HTTP, поддерживают TCP соединения. |
SOCKS5 | Самый гибкий вариант: поддерживает TCP/ UDP и различные методы аутентификации. |
В рамках nLevel - Прокси, типы HTTP и HTTPS обрабатываются как единая категория HTTP/HTTPS. Если вы укажете http, https, или http,https в параметре type, вы получите смешанный список прокси обоих этих типов.
Форматы ответа
Текстовый режим ( format=text)
Файл содержит только прокси. Формат строк зависит от количества выбранных типов: IP:PORT для одного типа и IP:PORT|TYPE, если форматы смешаны.
JSON режим ( format=json)
Ответ представляет собой объект с полем message и массивом proxies. Записи содержат обязательные поля ( ip, port, type) и дополнительные свойства вроде responseTimeMs и блока geo. Никаких служебных метаданных и статистики в выдаче нет — только данные о прокси.
Используйте точечную нотацию в параметрах filter для вложенных полей (например, filter=geo.city:Berlin), а значение * проверяет наличие непустого поля.
Полный справочник полей
Структура JSON содержит статус message и массив proxies. Каждый объект прокси может включать базовые поля и дополнительные сведения, если они есть в источнике.
Поля верхнего уровня
| Поле | Тип | Описание |
|---|---|---|
message | string | Статус запроса (например, success). |
proxies | Proxy[ | Массив объектов прокси после применения фильтров. |
Поля объекта Proxy
| Поле | Тип | Описание |
|---|---|---|
ip | string | IPv4-адрес узла, через который будут идти запросы. |
port | number | Порт, на котором прокси принимает подключения клиентов. |
type | string | Нормализованный тип протокола: HTTP/ HTTPS, SOCKS4 или SOCKS5. |
anonymity | string | Классификация уровня анонимности, которую возвращает источник (например, anonymous, elite). |
responseTimeMs | number | Средний отклик прокси в миллисекундах по данным последнего health-check. |
successfulChecks | number | Сколько раз подряд прокси подтверждал работоспособность. |
geo | object | Структурированный блок с геоданными (страна, регион, город, координаты и др.), который автоматически вычисляется и нормализуется. |
Поля объекта geo
| Поле | Тип | Описание |
|---|---|---|
country | string | ISO-код страны, определённый после нормализации данных. |
region | string | Регион или штат, к которому относится IP. |
city | string | Город расположения прокси. |
latitude | number | Географическая широта в градусах. |
longitude | number | Географическая долгота в градусах. |
timezone | string | Часовой пояс, определённый для IP-адреса. |
isp | string | Провайдер или оператор связи, обслуживающий IP. |
organization | string | Организация-владелец подсети, если известна. |
asn | string | Номер автономной системы (ASN). |