proxyMgr API 매뉴얼

실시간으로 수집·검증된 무료 프록시 목록을 가져다 쓰기 위한 REST API. 모든 엔드포인트는 인증 없이 사용한다.

• Base URL: https://proxy.gulu.kr
• 응답: JSON (Content-Type: application/json)
• 시간 값은 모두 UTC (YYYY-MM-DD HH:MM:SS)
• 백그라운드에서 약 244개 소스를 30분마다 수집하고, 각 프록시의 생존/HTTPS/익명도/지연/국가를 계속 재검증한다.

이 문서의 모든 URL·응답·예제는 실제 서버에 대해 검증된 것이다(2026-06-18).

---

빠른 시작 (TL;DR)

# 1) 바로 쓸 수 있는(usable) 프록시를 지연시간 빠른 순으로 가져오기
curl 'https://proxy.gulu.kr/api/proxies?status=usable&sort=latency&limit=20'

# 2) 받은 목록에서 하나 골라 실제로 사용 (socks5 예시)
curl --socks5-hostname 49.143.59.205:110 https://api.ipify.org
#   -> 49.143.59.205  (프록시의 IP가 출력되면 정상 동작)

status=usable은 즉시 사용 가능한 프록시만 준다(아래 "usable 규칙" 참조). 가장 흔한 사용 패턴이다.

---

엔드포인트

GET /api/proxies — 프록시 목록

가장 핵심 엔드포인트. 필터·정렬·페이지네이션을 지원한다.

쿼리 파라미터 (모두 선택)

이름	값	기본값	설명
status	usable | alive | all	usable	usable=바로 사용 가능, alive=마지막 검사에서 살아있음, all=전체
protocol	http | socks5	(전체)	프로토콜 필터
country	국가코드 (예: KR, US)	(전체)	ISO 2자리, 대소문자 무관
anonymity	elite | anonymous | transparent	(전체)	익명도
https	1 | true | yes	(무관)	HTTPS(CONNECT) 터널링 지원만
max_latency	정수(ms)	(무제한)	이 지연시간 이하만
sort	latency | checked | country | uptime	latency	정렬 기준
limit	정수 (최대 2000)	200	페이지 크기
offset	정수	0	페이지 오프셋

잘못된 값은 HTTP 422로 거부된다(예: status=bogus, limit=abc).

예시 URL

https://proxy.gulu.kr/api/proxies?status=usable&sort=latency&limit=20
https://proxy.gulu.kr/api/proxies?status=usable&protocol=socks5&country=KR
https://proxy.gulu.kr/api/proxies?status=alive&protocol=http&https=1&anonymity=elite
https://proxy.gulu.kr/api/proxies?status=usable&sort=uptime&max_latency=1000
https://proxy.gulu.kr/api/proxies?status=alive&limit=100&offset=100

응답 (실제 예시)

{
  "count": 3,
  "total": 8,
  "offset": 0,
  "proxies": [
    {
      "ip": "49.143.59.205",
      "port": 110,
      "protocol": "socks5",
      "country": "South Korea",
      "country_code": "KR",
      "anonymity": "unknown",
      "https": 1,
      "latency_ms": 119,
      "alive": 1,
      "usable": 1,
      "sources": "proxyscrape,proxyscrape-api-v4,stormsia-proxy-list-socks5,...",
      "last_checked": "2026-06-18 12:02:40",
      "last_alive": "2026-06-18 12:02:40",
      "check_count": 1,
      "success_count": 1,
      "checked_age_s": 334,
      "alive_age_s": 334
    }
  ]
}

필드 설명

필드	설명
ip, port, protocol	접속 정보 (http 또는 socks5)
country, country_code	출구(exit) 국가
anonymity	elite(IP·프록시 흔적 모두 숨김) / anonymous(프록시 흔적 노출) / transparent(실 IP 노출) / unknown
https	1이면 HTTPS(CONNECT) 터널링 지원 — HTTPS 사이트에 사용 가능
latency_ms	마지막 검사 시 응답 지연(ms)
alive	마지막 검사에서 살아있었는지 (1/0)
usable	"바로 쓸 수 있음" 플래그 (아래 규칙)
sources	이 프록시를 보고한 소스 이름(콤마 구분)
last_checked, last_alive	마지막 검사 / 마지막 생존 시각 (UTC)
check_count, success_count	누적 검사/성공 횟수 (가동률 계산용)
checked_age_s, alive_age_s	마지막 검사/생존 이후 경과 초 (서버가 UTC로 계산해 내려줌 — 신선도 판단에 사용)

응답 최상위의 count=이번 페이지 행 수, total=필터 일치 총 개수, offset=요청 오프셋.

---

GET /api/stats — 요약 통계

https://proxy.gulu.kr/api/stats

{
  "total": 515399,
  "alive": 40,
  "usable": 9,
  "checked": 172247,
  "by_protocol": { "socks5": 9 },
  "by_anonymity": { "elite": 5, "unknown": 35 },
  "last_check_at": "2026-06-18 12:07:13"
}

by_protocol은 usable 기준, by_anonymity는 alive 기준 집계.

---

GET /api/countries — 국가 목록

usable 프록시가 있는 국가를 건수 내림차순으로.

https://proxy.gulu.kr/api/countries

[
  { "country_code": "JP", "country": "Japan", "c": 2 },
  { "country_code": "KR", "country": "South Korea", "c": 2 },
  { "country_code": "SG", "country": "Singapore", "c": 2 }
]

---

GET /api/sources — 소스별 기여 현황

등록된 약 244개 소스와 각 소스가 기여한 프록시 수(30초 캐시).

https://proxy.gulu.kr/api/sources

{
  "count": 244,
  "enabled": 229,
  "sources": [
    {
      "name": "vmheaven-vmheaven-io-free-proxy-list",
      "kind": "text",
      "reliability": "medium",
      "enabled": true,
      "protocols": ["http", "socks5"],
      "note": "vmheaven/vmheaven.io-free-proxy-list (GitHub raw)",
      "urls": ["https://raw.githubusercontent.com/.../http.txt", "..."],
      "total": 6311,
      "alive": 8,
      "usable": 5
    }
  ]
}

usable/alive/total 내림차순 정렬.

---

POST /api/collect — 수동 수집 트리거 (관리용)

모든 소스를 즉시 1회 재수집한다. 백그라운드가 30분마다 자동 수행하므로 보통은 필요 없다. 완료까지 약 1분 블록되며 요약을 반환한다.

curl -X POST https://proxy.gulu.kr/api/collect

{ "total_unique": 507742, "sources_ok": 222, "per_source": { "fyvri-fresh-proxy-list": 453414, "...": 0 } }

---

프록시 사용 예시 (검증됨)

API에서 받은 프록시를 실제로 쓰는 방법. 49.143.59.205:110(socks5, KR)로 실측 검증됨 — 프록시 경유 시 exit IP가 프록시 IP로 바뀐다.

curl

# socks5  (DNS도 프록시에서 해석: --socks5-hostname)
curl --socks5-hostname 49.143.59.205:110 https://api.ipify.org      # -> 49.143.59.205

# http 프록시
curl -x http://IP:PORT https://api.ipify.org

Python (pip install "requests[socks]")

import requests

# 1) usable 프록시들을 받아 살아있는 것을 만날 때까지 시도(무료 프록시는 자주 죽으므로 폴백 필수)
proxies = requests.get("https://proxy.gulu.kr/api/proxies",
                       params={"status": "usable", "sort": "latency", "limit": 20}).json()["proxies"]
for p in proxies:
    scheme = "socks5h" if p["protocol"] == "socks5" else "http"
    proxy_url = f"{scheme}://{p['ip']}:{p['port']}"
    try:
        r = requests.get("https://api.ipify.org",
                         proxies={"http": proxy_url, "https": proxy_url}, timeout=15)
        print("exit ip:", r.text)   # 프록시의 IP가 나오면 성공
        break
    except Exception:
        continue   # 다음 프록시로 폴백

Node.js (npm i socks-proxy-agent) — 실측 검증된 패턴

import https from 'node:https';
import { SocksProxyAgent } from 'socks-proxy-agent';

const list = await (await fetch(
  'https://proxy.gulu.kr/api/proxies?status=usable&protocol=socks5&sort=latency&limit=20'
)).json();

for (const p of list.proxies) {
  const agent = new SocksProxyAgent(`socks5h://${p.ip}:${p.port}`, { timeout: 8000 });
  const exitIp = await new Promise((resolve) => {
    const req = https.request({ hostname: 'api.ipify.org', path: '/', agent, timeout: 10000 },
      (r) => { let d = ''; r.on('data', (c) => d += c); r.on('end', () => resolve(d.trim())); });
    req.on('error', () => resolve(null));
    req.on('timeout', () => { req.destroy(); resolve(null); });
    req.end();
  });
  agent.destroy();
  if (exitIp) { console.log('exit ip:', exitIp); break; }   // 성공 → 사용; 실패 시 다음 프록시로 폴백
}

---

권장 사용 패턴

• status=usable를 기본으로 사용한다. socks5는 살아있으면 usable, http는 elite + https까지 만족해야 usable이다.
• 신선도 확인: checked_age_s가 작은(예: < 600초) 프록시를 우선 사용한다. 무료 프록시는 수명이 짧다.
• 여러 개를 받아 로테이션한다(limit을 넉넉히). 개별 프록시는 언제든 죽을 수 있으니 실패 시 다음 것으로 폴백한다.
• HTTPS 대상이면 https=1로 필터하거나 https 필드가 1인 것을 쓴다.
• 폴링 주기는 30초~몇 분이면 충분하다(검증 루프가 alive 프록시를 약 10분마다 갱신).

usable 규칙

usable = (protocol == "socks5" && alive)
       || (protocol == "http"   && alive && anonymity == "elite" && https)

오류

상황	응답
잘못된 status	`422 {"detail":"status must be one of usable
limit/offset/max_latency 가 정수 아님	422 {"detail":"... must be an integer"}