Good Proxies

API документация

Справочник по API Good Proxies: как собирать запросы к единому endpoint, получать TXT/JSON выдачу и учитывать лимиты ключа, демо-режима и временных ссылок.

Содержание
  • Endpoint/api/
  • ФорматыTXT, JSON, *.file
  • Тестовый ключdemo
Навигация

Как читать эту документацию

Сначала общий контекст и лимиты, затем конструирование URL, таблица параметров, режимы вывода и примеры кода — весь справочник на одной странице.

Удобная навигация: плотное оглавление, предупреждения об ошибках, описание лимитов, справочник параметров и живые примеры запросов.
Документация отражает все возможности backend: get=txt|json|*.file, JSON-поля fields/split_ip/wrap/format/pretty, type_prefix, country_mode и service.
Только задокументированные методы: страница описывает именно то, что реально поддерживает /api/, без несуществующих endpoint'ов.
01

Общие сведения

Reference

Good Proxies использует единый endpoint /api/. Все фильтры, режимы выдачи и JSON-настройки задаются GET-параметрами. Ответы об ошибках приходят в JSON envelope с кодом, сообщением и timestamp.

  • Запрос всегда начинается с параметра key и может быть расширен фильтрами по типу, анонимности, скорости, ping, времени проверки, стране, городу, порту и сервисной совместимости.
  • Режим выдачи задаётся параметром get: txt по умолчанию, а также json, txt.file и json.file.
  • Для JSON доступны дополнительные настройки: fields, split_ip, format=array|object, wrap и pretty.
  • Локализация ответа задаётся параметром lang. При lang=en API возвращает city_en, если английское название города есть в базе.
Важно. API-ссылка содержит секретный ключ доступа. Не публикуйте её в клиентском коде, логах браузера или сторонних shared scripts.

Быстрый старт

https://good-proxies.com/api/?key=YOUR_KEY&type=http&country=ru&count=10

Поддерживаемые режимы выдачи

get=txt get=json get=txt.file get=json.file
02

HTTP-коды ответа

Reference

При успешном запросе API возвращает список прокси, при ошибке — JSON с полями status, code, message и timestamp, а при необходимости ещё и контекст вроде retry_after, daily_limit или used_subnets.

HTTP Параметр Описание Пример
200 OK Подходящие прокси найдены и возвращены в выбранном формате. {"status":"ok", ...}
400 KEY_MISSING Параметр key не передан. {"code":"KEY_MISSING"}
403 INVALID_KEY / TEMP_KEY_INVALID Ключ доступа недействителен, истёк или временная ссылка больше не активна. {"code":"INVALID_KEY"}
404 PROXIES_NOT_FOUND По выбранным фильтрам ничего не найдено. {"code":"PROXIES_NOT_FOUND"}
429 RATE / LIMIT / SUBNET Сработал burst-limit, демо-limit, лимит временной ссылки, дневной лимит запросов или лимит подсетей. {"code":"DAILY_LIMIT_REACHED"}
500/503 DB / CACHE failure Внутренняя ошибка базы или кеша, выдача недоступна. {"code":"DB_EXECUTE_FAILED"}
{ "status": "ok", "count": 2, "timestamp": "2026-04-23T12:00:00Z", "filters": { "type": "socks5", "country": "us", "service": "telegram" }, "data": [ { "ip": "198.51.100.10", "port": "1080", "type": "socks5", "country": "US", "city": "New York" }, { "ip": "198.51.100.11", "port": "1080", "type": "socks5", "country": "US", "city": "Chicago" } ] }
{ "status": "error", "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests. Please try again later.", "timestamp": "2026-04-23T12:00:05Z", "retry_after": 5 }
03

Ограничения

Reference

Лимиты зависят не только от тарифа, но и от режима ключа. В коде backend сейчас применяются следующие окна защиты и квоты.

  • Премиум ключ: burst-limit до 5 запросов за 5 секунд на ключ. При превышении API возвращает 429 RATE_LIMIT_EXCEEDED и retry_after.
  • Ключ demo: не более 2 запросов в минуту на IP, результат ограничен 50 прокси, а при отсутствии фильтра works автоматически используется значение 90.
  • Временные ссылки temp_...: не более 2 запросов в час на саму ссылку и 2 запросов в час на IP, результат ограничен 30 прокси.
  • Для обычного ключа дополнительно контролируются дневной лимит обращений и суточный лимит уникальных подсетей, разрешённых тарифом.
  • Если count не задан, API берёт внутренний лимит по вашему ключу; demo и temp режимы применяют свои жёсткие потолки автоматически.
Предупреждение. Частые нерезультативные обращения с неверным ключом или постоянно превышенными лимитами не ускоряют выдачу: сначала вы увидите 429/403, а затем потеряете время на повторные ретраи. Лучше сузить фильтр и уважать retry_after.
Примечание. Для фильтров по странам важно помнить про лимит подсетей: если запрос слишком широкий, API может вернуть SUBNET_LIMIT_REACHED даже при действующем тарифе.
04

Тестовый и временный доступ

Reference

API поддерживает два специальных режима доступа внутри одного endpoint /api/: тестовый ключ demo и временные ссылки с префиксом temp_.

Как использовать. Демо-ответы маскируются и нужны только для проверки интеграции. Временные ссылки больше подходят для короткоживущей раздачи API URL внутри сервиса, а не для постоянного использования.
  • Ключ demo удобен для первого запроса, проверки формата JSON и базовой совместимости клиента.
  • Временная ссылка проверяется отдельно и отваливается по сроку действия; при ошибке вы получите TEMP_KEY_INVALID.
  • Оба режима расходуют собственные rate-limit окна и не заменяют полноценный ключ доступа из кабинета.
https://good-proxies.com/api/?key=demo&type=http&anon=elite&count=10&get=json&wrap=1
05

Как сконструировать запрос

Reference

Запрос строится по одной схеме: ключ, фильтры, режим выдачи. Удобнее всего настроить фильтр через веб-интерфейс и скопировать готовый URL, а вручную добавить только те параметры, которых нет в UI.

  • Начните с key и выберите фильтры type, anon, country, city, service, ping, speed, time, works и count.
  • Если нужно исключить страны, передайте country_mode=except или короткий алиас cm=except.
  • Для JSON укажите get=json и при необходимости добавьте fields, split_ip=1, format=object или wrap=1.
  • Для TXT с префиксом типа используйте type_prefix=1. Для скачивания файла вместо inline-ответа переключайтесь на txt.file или json.file.
Не перепутайте. Не смешивайте параметр get с JSON-параметром format: первый выбирает сам тип ответа, второй меняет только внутреннюю форму JSON (array или object).
https://good-proxies.com/api/?key=YOUR_KEY&type=socks4,socks5&anon=elite&country=us,gb&city=new york,london&service=telegram&ping=120&time=300&count=100&get=json&fields=ip,port,type,country,city&split_ip=1&wrap=1&lang=en
06

Описание параметров

Reference
Параметр Обяз. Описание Пример
key Да Ключ доступа. Поддерживаются обычные ключи, demo и временные ключи temp_.... demo
type Нет Список типов прокси через запятую: http, https, socks4, socks5. http,socks5
anon Нет Список уровней анонимности: transparent, anonymous, elite. elite
speed Нет Минимальная скорость в байтах в секунду. 150000
ping Нет Максимально допустимый ping в миллисекундах. 120
time Нет Максимальный возраст последней проверки в секундах. По умолчанию — 600. 300
works Нет Минимальная работоспособность в процентах. 90
country Нет Коды стран ISO 3166-1 alpha-2 в нижнем регистре, через запятую. ru,us,de
country_mode / cm Нет Режим фильтра по странам: include по умолчанию или except для исключения выбранных стран. except
city Нет Список городов через запятую. При lang=en фильтрация идёт по city_en, если значение доступно. moscow,new york
port Нет Точный номер порта. 8080
service Нет Фильтр по сервисной совместимости: smtp, telegram, avito, google, mail. telegram
count Нет Число прокси в ответе. Ограничивается режимом ключа и тарифом. 100
get Нет Режим выдачи: txt (по умолчанию), json, txt.file, json.file. json.file
fields Нет Только для JSON. Список полей: ip, port, ip_out, type, anon, speed, ping, timecheck, country, city, works, smtp, telegram, avito, google, mail. ip,port,type,country,city
split_ip Нет Только для JSON. Если 1, строка ip:port разбивается на отдельные поля ip и port. 1
format Нет Только для JSON. Внутренняя форма данных: array или object, где ключом становится адрес прокси. object
wrap Нет Только для JSON. Если 1, ответ оборачивается в envelope со статусом, timestamp, filters и data. 1
pretty Нет Только для JSON. 1 — pretty-print, 0 — компактный JSON. 0
type_prefix Нет Только для TXT. Если 1, каждая строка получает префикс type://. 1
lang Нет Язык локализации ответа: ru или en. en
07

Форматы выдачи

Reference

Good Proxies поддерживает выдачу в форматах TXT и JSON. Режимы скачивания файла возвращают тот же контент, но со специальными заголовками ответа.

Замечание. CSV в текущем backend не поддерживается, поэтому его нет в таблице режимов и примерах.

TXT inline

Режим по умолчанию. Возвращает список вида ip:port; при type_prefix=1 — type://ip:port.

https://good-proxies.com/api/?key=YOUR_KEY&type=http&count=10&type_prefix=1

JSON API

Структурированный ответ с поддержкой fields, split_ip, wrap, format=object и pretty=0.

https://good-proxies.com/api/?key=YOUR_KEY&get=json&fields=ip,port,type,country,city&split_ip=1&wrap=1&lang=en

File download

Режимы txt.file и json.file используют тот же payload, но отдают его как скачиваемый файл.

https://good-proxies.com/api/?key=YOUR_KEY&get=json.file&type=socks5&country=us&count=25
198.51.100.10:8080 https://198.51.100.11:443 socks5://198.51.100.12:1080
{ "status": "ok", "count": 2, "timestamp": "2026-04-23T12:00:00Z", "filters": { "type": "socks5", "country": "us", "service": "telegram" }, "data": [ { "ip": "198.51.100.10", "port": "1080", "type": "socks5", "country": "US", "city": "New York" }, { "ip": "198.51.100.11", "port": "1080", "type": "socks5", "country": "US", "city": "Chicago" } ] }
08

Примеры запросов

Reference
cURL

Получить 10 HTTP прокси из России в TXT

curl "https://good-proxies.com/api/?key=YOUR_KEY&type=http&country=ru&count=10"
PHP

Получить JSON envelope с выборкой по сервису Telegram

$url = 'https://good-proxies.com/api/?key=YOUR_KEY&get=json&service=telegram&count=20&wrap=1&fields=ip,port,type,country,city'; $data = json_decode(file_get_contents($url), true); print_r($data['data']);
Python

Получить элитные прокси с ping < 100 мс

import requests response = requests.get('https://good-proxies.com/api/', params={ 'key': 'YOUR_KEY', 'anon': 'elite', 'ping': 100, 'count': 50, 'get': 'json', 'pretty': 0, }) print(response.json())
JavaScript

Получить SOCKS5 по США с англоязычными городами

const url = 'https://good-proxies.com/api/?key=YOUR_KEY&type=socks5&country=us&get=json&lang=en&split_ip=1&fields=ip,port,country,city'; fetch(url).then(r => r.json()).then(console.log);
09

Заметки по текущей версии API

Reference
  • Параметр lang=en локализует названия городов через поле city_en, если оно заполнено.
  • Фильтр по странам поддерживает режим исключения через country_mode=except или cm=except.
  • JSON-режим умеет возвращать сокращённые поля через fields, split IP/port, object-format и envelope через wrap=1.
  • API может фильтровать совместимость по сервисам smtp, telegram, avito, google и mail.
  • Для TXT добавлен режим type_prefix=1, а для demo/temp ключей действуют отдельные лимиты по скорости обращений и размеру ответа.
Связанные страницы

Если вы хотите собрать URL без ручного редактирования или проверить, как фильтры работают вживую, переходите в кабинет, FAQ и соседние справочные разделы.