Последняя редакция: 01.03.2024
API сервиса Best-Proxies.ru - это инструмент, позволяющий Премиум пользователям сервиса выгружать списки прокси с заданными характеристиками в форматах TXT, CSV и JSON, что позволяет использовать свежие рабочие прокси в программном обеспечении. В данном руководстве содержится информация о том, как правильно формировать запросы к API сервиса, а также о форматах, в которых возвращаются списки прокси.
Актуальный таймаут проверки прокси сервисом - 5 секунд.
Для выгрузки списка прокси в формате TXT необходимо отправить HTTP GET-запрос на адрес http://api.best-proxies.ru/proxylist.txt или, с использованием защищённого протокола SSL на адрес https://api.best-proxies.ru/proxylist.txt.
Для выгрузки списка прокси в формате CSV необходимо отправить HTTP GET-запрос на адрес http://api.best-proxies.ru/proxylist.csv или, с использованием защищённого протокола SSL на адрес https://api.best-proxies.ru/proxylist.csv.
Для выгрузки списка прокси в формате JSON необходимо отправить HTTP GET-запрос на адрес http://api.best-proxies.ru/proxylist.json или, с использованием защищённого протокола SSL на адрес https://api.best-proxies.ru/proxylist.json.
Для получения информации о своём ключе Премиум доступа необходимо отправить HTTP GET-запрос на адрес http://api.best-proxies.ru/key.txt или, с использованием защищённого протокола SSL на адрес https://api.best-proxies.ru/key.txt.
Поддерживаемые протоколы SSL TLSv1.2 TLSv1.3.
Характеристики выгружаемых прокси, их количество и формат, в котором они будут выгружены, задаются при помощи GET-параметров.
limit (см. описание) (HTTP код ответа 200);API-интерфейс возвращает следующие HTTP-коды ответа. В случае ошибки (код ответа отличный от 200), возвращается HTML-отформатированная страница с расширенным описанием ошибки.
| Код ответа | Описание |
|---|---|
| 200 | Успешный ответ. |
| 400 | Ошибка синтаксиса запроса. |
| 401 | Указанный ключ Премиум-доступа не существует. |
| 403 | Указанный ключ Премиум-доступа не активен (окончен, просрочен, заблокирован или не активирован) или если обращение происходит из сети TOR или через открытые прокси. |
| 429 | Превышено максимально допустимое число обращений (15 в минуту) для одного IP или ключа. Или превышено максимально допустимое количество IP x.x.0.0/16 сетей при обращениях с одним ключом в сутки. Подробнее написано здесь. |
Списки прокси обновляются, примерно, один раз в 30 секунд, Для обеспечения рационального использования вычислительных ресурсов оборудования Сервиса, на обращения к API интерфейсу действуют следующие ограничения:
Сконструировать ссылку на получение прокси с необходимыми характеристиками можно при помощи фильтра прокси в веб-интерфейсе. Для этого необходимо установить нужные значения фильтра и нажать кнопку «Применить», после чего, в случае, если будут найдены соответствующие прокси, в нижней части фильтра появятся ссылки на получение прокси, с заданными характеристиками, в форматах TXT, CSV и JSON. Обратите внимание, что некоторые параметры недоступны в веб-фильтре. Данные ссылки можно скопировать в буфер обмена при помощи расположенных справа от них кнопок. Ссылки будут работать на протяжении всего срока действия ключа Премиум доступа.
Для тестирования работы API со своим ПО, разработчики могут использовать специальный ключ developer. С помощью данного ключа можно получить список из, не более, чем 10 прокси в любом из доступных форматов (TXT, CSV, JSON). При этом, в запросе вы можете указывать все доступные параметры фильтра, но, реально влиять на выборку будут только параметры type, includeType и limit (в пределах от 1 до 10, если значение данного параметра не будет указано, либо, будет равно 0, либо, будет больше 10, ему будет присвоено значение 10), остальные параметры, указанные в запросе, будут проигнорированы.
С помощью данного ключа нельзя получить текущие характеристики списка прокси.
| Имя | Описание |
|---|---|
| key | Ваш ключ Премиум доступа, единственный обязательный параметр. Вы также можете указать тестовый ключ для разработчиков для целей тестирования. |
| type | Тип выгружаемых прокси, допустимые значения: http, https, socks4, socks5. Можно указать несколько, через запятую. Если этот параметр не задан, будут выгружены прокси всех типов. |
| level | Уровень анонимности выгружаемых прокси серверов, допустимые значения: 1, 2, 3, 1 - соответствует высоко анонимным (элитным) прокси, 2 - соответствует анонимным прокси, 3 - соответствует прозрачным прокси. Можно указать несколько, через запятую.Внимание Если этот параметр не задан, будут выгружены прокси всех уровней анонимности, в т.ч. прозрачные, которые раскрывают реальный IP адрес клиента. Подробнее об уровнях анонимности прокси читайте в нашей базе знаний. |
| bl NEW |
Уровень присутствия исходящего IP прокси (может отличаться от IP покдлючения) в чёрных списках DNSBL, на основании листинга в которых, доступ через прокси может быть ограничен на некоторых ресурсах. Отбор прокси с более «чистыми» IP, как можно в меньшей степени присутствующих в DNSBL, повышает шансы выполнения успешных запросов к тем ресурсам, на которых учитываются данные списков DNSBL. Значением данного параметра должно быть число от 0 до 10 (1-10 процентная шкала с шагом в 10%, а также 0), где 0 - наилучший результат, когда IP не присутствует ни в одном из DNSBL, проверяемых нами, а 10 - наихудший, когда IP присутствует в 91-100% проверяемых DNSBL. Заданное число характеризует максимально допустимый уровень присутствия в списках. Например, если задать число 4, то будут возвращены прокси, каждый из которых присутствует не более, чем в 40% проверяемых нами списках DNSBL, если задать число 0, то будут возвращены прокси с самыми «чистыми» IP, не присутствующими ни в одном из списков, если не задать данный параметр, будут возвращены прокси с любым уровнем присутствия в DNSBL. Подробнее о DNSBL читайте в нашей базе знаний. Список DNSBL, в которых проверяется присутствие IP прокси на данный момент:
|
| ports | Список портов выгружаемых прокси, можно указать до пяти через запятую. Данный параметр можно использовать, если, например, необходимо выгрузить прокси на стандартных портах (80, 443, 1080, 3128, 8080). Данный параметр нельзя задать через веб-фильтр. |
| pex | Если равен 1, то вернутся прокси с портами, отсутствующими в списке, заданном параметром ports. |
| country | Двубуквенные коды стран выгружаемых прокси в соответствии с ISO 3166-1 alpha-2, можно указать до 20 через запятую. |
| cex | Если равен 1, то вернутся прокси из стран, отсутствующих в списке, заданном параметром country. |
| response | Числовое значение максимального времени отклика (в миллисекундах) выгружаемых прокси (обычно, в пределах ~250-3500), обратите внимание, замеряется скорость ответа прокси нашему серверу, в вашем случае, скорость соединения может быть другой. |
| uptime | Числовое значение времени непрерывной работы прокси в часах, допустимые значения находятся в диапазоне 1 - 48. На заметку Параметр также может принимать значение «30m», что соответствует 30 минутам. |
| speed | Скоростной грейд выгружаемых прокси серверов, в зависимости от времени, затраченного на выполнение теста прокси, допустимые значения: 1 (быстрые), 2 (средние по скорости), 3 (медленные). Можно указать несколько, через запятую. |
Если равен 1, то вернутся прокси с открытым 25 SMTP портом. Обратите внимание, что отправки почты невозможна через обычные HTTP прокси, а только через HTTPS или SOCKS прокси.Внимание Для прокси, соответствующих данному параметру, не проверяется наличие IP адреса в списках RBL, что может воспрепятствовать отправке почты через данные прокси. |
|
Если равен 1, то возвращаются прокси, через которые возможны запросы к ПС Google без ввода капчи. |
|
| mailru | Если равен 1, то возвращаются прокси, работающие на проектах mail.ru, (HTTP, а не SMTP доступ). |
| telegram | Если равен 1, то возвращаются прокси, работающие с API мессенджера Телеграм (Telegram). |
| avito | Если равен 1, то возвращаются прокси, работающие с API сервиса объявлений Авито (Avito). |
| includeType | Данный параметр влияет на формат выводимого списка прокси в формате TXT. Если передать этот параметр без значения, то прокси возвращаются в формате [type]://[ip]:[port]. Если этот параметр не указан, список возвращается в формате [ip]:[port]. Подробнее о форматах вывода списка прокси читайте ниже. |
| limit | При помощи этого параметра задаётся максимальное количество выгружаемого списка прокси. Если этот параметр равен 0, выводится список из не более чем 15.000 прокси. Если этот параметр не задан, выводится список, не более чем из 20 прокси. |
| nocascade | Если равен 1, то возвращаемый список не содержит каскадных прокси. Данный параметр нельзя задать через веб-фильтр. |
| filename | Данный параметр используется для задания имени сохраняемого файла со списком прокси в текстовом формате. Параметр указывается, если необходимо выполнить сохранение списка прокси в текстовом формате, вместо того, чтобы открыть его в окне браузера. Данный параметр игнорируется при обращении к списку в форматах CSV и JSON. Значение параметра может содержать от 3 до 10 символов из набора A-Za-z0-9. Если значение параметра будет удовлетворять этому условию, будет сохранён файл с расширением .txt, иначе, параметр будет проигнорирован, и, при отсутствии ошибок в значениях других параметров, список прокси откроется в окне браузера. Данный параметр нельзя задать через веб-фильтр. |
Формат TXT
Вывод списка прокси возможен в двух форматах. По-умолчанию, если не задан параметр includeType, прокси выводятся в формате [ip]:[port] по одному в каждой строке, например:
127.0.0.1:3128 127.0.0.2:1080
Если задан параметр includeType, то прокси выводятся с указанием типа (поддерживаемого протокола) в формате [type]://[ip]:[port], где type может принимать значения http, https, socks4 или socks5. Если прокси поддерживает все протоколы, то указан будет наиболее функциональный из них - socks5. Пример списка:
http://127.0.0.1:3128 https://127.0.0.1:443 socks4://127.0.0.2:1080 socks5://127.0.0.3:8080
Такой формат поддерживается для использования в CURL . Чтобы проинструктировать CURL работать через прокси, достаточно указать прокси в формате [type]://[ip]:[port] в параметре CURLOPT_PROXY , например:
$proxy = "socks4://127.0.0.2:1080";
$ch = curl_init();
list($proxy_type, $proxy_addr) = explode('://', $proxy);
if($proxy_type == 'https')
{
// Тип прокси в данном случае HTTP, но, для него необходимо использовать туннелирование (метод CONNECT)
$proxy_type = 'http';
curl_setopt($ch, CURLOPT_HTTPPROXYTUNNEL, true);
}
curl_setopt($ch, CURLOPT_PROXY, $proxy_type.'://'.$proxy_addr);
...
$response = curl_exec($ch);
curl_close($ch);
Формат CSV
Выгрузка в формате CSV производится в кодировке windows-1251. Набор полей, включая порядок их следования фиксированный, разделитель полей - ;. Первая строка выгружаемого файла содержит описание полей. Наименования городов и регионов (штатов, областей) выгружаются на английском языке. Пример выгружаемого файла:
"ip";"port";"country code";"city";"region";"country";"level";"http";"https";"socks4";"socks5";"google";"telegram";"avito";"mailru";"real_ip";"response";"good checks";"bad checks";"hostname" "192.168.0.1";9090;"KZ";"Almaty";"";"Kazakhstan";3;1;0;0;0;1;0;1;0;1;"192.168.5.12";352;10;0;"host1.localhost" "192.168.1.1";3128;"DE";"Frankfurt am Main";"Hesse";"Germany";3;1;1;0;1;0;1;1;0;1;"192.168.1.1";511;17;102;12;"host2.localhost" "192.168.5.1";3128;"TH";"Bangkok";"";"Thailand";3;1;0;0;0;0;1;1;0;1;"192.168.5.1";290;1;1;"192.168.5.1"
Значения полей соответствуют соответствующим параметрам запроса.
Формат JSON
Выгрузка в формате JSON производится в кодировке UTF-8, многобайтовые символы Unicode не кодируются. Наименования городов и регионов (штатов, областей) выгружаются на английском языке. Пример выгружаемого файла:
[
{
"ip": "192.168.0.1",
"port": 1080,
"hostname": "host.localhost",
"http": 0,
"https": 0,
"socks4": 1,
"socks5": 0,
"level": 1,
"google": 1,
"mailru": 1,
"telegram": 0,
"avito": 0,
"country_code": "RU",
"response": 318,
"good_count": 48,
"bad_count": 0,
"last_check": "2018-08-02 17:24:36",
"city": "Voronezh",
"region": "",
"real_ip": 192.168.0.100,
"test_time": 1.4,
"me": 1
},
{
"ip": "192.168.0.2",
"port": 8080,
"hostname": "192.168.0.2",
"http": 1,
"https": 1,
"socks4": 0,
"socks5": 0,
"level": 1,
"google": 1,
"instagram": 0,
"telegram": 1,
"avito": 1,
"country_code": "US",
"response": 84",
"good_count": 1,
"bad_count": 0,
"last_check": "2018-08-02 17:26:02",
"city": "Sheridan",
"region": "Arkansas",
"real_ip": "192.168.0.2",
"test_time": 2.9,
"me": 0
}
]Описание полей
ip – IP адрес подключения;port – порт подключения;hostname – имя хоста результирующего IP;http – поддержка протокола HTTP (1 - поддерживает, 0 - не поддерживает);https – поддержка метода CONNECT (1 - поддерживает, 0 - не поддерживает);socks4 – поддержка протокола SOCKS4 (1 - поддерживает, 0 - не поддерживает);socks5 – поддержка протокола SOCKS5 (1 - поддерживает, 0 - не поддерживает);level – уровень анонимности (1 - высоко анонимный, 2 - анонимный, 3 - прозрачный);google – прокси для обращения к Google без капчи (1 - да, 0 - нет);mailru – прокси для HTTP обращения @Mail.Ru (1 - да, 0 - нет);telegram – прокси для Телеграм (Telegram) (1 - да, 0 - нет);avito – прокси для Авито (Avito) (1 - да, 0 - нет);country_code – двубуквенный коды страны в соответствии с ISO 3166-1 alpha-2*;response – время отклика, мсек;good_count – количество успешных тестов прокси (0-65535);bad_count – количество неуспешных тестов прокси (0-65535);last_check – время последней проверки в формате YYYY-MM-DD HH:MM:SS;city – город*;region – область/штат*;real_ip – результирующий IP адрес;test_time – время, за которое прокси прошёл тест, в секундах;me – открыт 25 порт (1 - да, 0 - нет);* - в случае, если прокси каскадный (IP подключения отличается от результирующего IP), геоданные указываются для результирующего IP.
Для получения времени, оставшегося до окончания платной подписки, обходимо выполнить следующий HTTP GET запрос:
https://api.best-proxies.ru/key.txt?key=developer&format=[hours|minutes|seconds]
В запросе, тестовый ключ разработчика developer, необходимо заменить на ваш ключ Премиум доступа и указать в параметре format одно из значений: hours - для вывода оставшихся до окончания подписки полных часов, minutes - для вывода оставшихся до окончания подписки полных минут или seconds - для вывода оставшихся до окончания подписки секунд. Результатом выполнения запроса будет число оставшихся до окончания срока действия указанного в параметре key ключа Премиум доступа полных единиц времени, заданных параметром format. В случае, если оставшееся время меньше единицы - будет возвращен 0. Значение параметра format по-умолчанию - hours, т.е. если данный параметр не задан, будут возвращены часы. Как и API-запросы на получение списков прокси, данный запрос расходует отведённые для обращения к API лимиты.
Для получения текущих характеристик списка прокси в формате JSON, необходимо выполнить следующий HTTP GET запрос:
https://api.best-proxies.ru/stats.json?key=developer
В ответ вы получите:
{
"list": {
"alive": 4781,
"hidden": 1092,
"acttime": 5
},
"types": {
"http": 1710,
"https": 1129,
"socks4": 1843,
"socks5": 808
},
"levels": {
"high_anonymous": 4179,
"anonymous": 41,
"transparent": 561
},
"services": {
"smtp": 671,
"google": 291,
"telegram": 796,
"avito": 865,
"mailru": 792
},
"countries": {
"ae": "46",
"al": "15",
"am": "8",
...
"zw": "2"
}
}Описание полей
list/alive – Количество живых прокси (без учёта скрытых), доступных для использования;list/hidden – Количество скрытых живых прокси;list/acttime – Время актуальности списка прокси (минут);types/http – Количество HTTP прокси;types/https – Количество HTTPS прокси;types/socks4 – Количество SOCKS4 прокси;types/socks5 – Количество SOCKS5 прокси;levels/high_anonymous – Количество высоко-анонимных (элитных) прокси;levels/anonymous – Количество анонимных прокси;levels/transparent – Количество прозрачных прокси;services/smtp – Количество прокси с поддержкой отправки почты;services/google – Количество прокси с поддержкой Google без капчи;services/telegram – Количество прокси с доступом к Telegram;services/avito – Количество прокси с доступом к Avito;services/mailru – Количество прокси с доступом к Mail.ru;countries/XX – Данная секция содержит статистику по странам, где XX - двубуквенный код страны ISO 3166-1 alpha-2 в нижнем регистре. Выводятся только те коды стран, для которых количество живых прокси на момент выполнения запроса больше нуля;Выгрузить 10 анонимных HTTP прокси, с максимальным временем отклика 100 мсек:
https://api.best-proxies.ru/proxylist.txt?key=developer&limit=10&level=1,2&type=http&response=100
Выгрузить все* SOCKS прокси из России и Украины:
https://api.best-proxies.ru/proxylist.txt?key=developer&limit=0&type=socks4,socks5&country=ru,ua
Выгрузить 50 прокси на стандартных портах:
https://api.best-proxies.ru/proxylist.txt?key=developer&limit=50&ports=80,1080,8080,3128
Выгрузить все* анонимные прокси в формате с указанием типа прокси:
https://api.best-proxies.ru/proxylist.txt?key=developer&limit=0&level=1,2&includeType
* - не более 15.000 в соответствии с ограничениями.
текущих характеристик списка прокси;bl, позволяющий отбирать IP с ниаболее «чистой» репутацией;telegram;avito;yandex. Мы больше не проверяем прокси на доступ к поисковой системе Яндекс без капчи, в виду сохраняющегося продолжительное время низкого количества таких прокси;http://... вместо защищённого https://....