API dokümantasyonu

Genel kurallar

• Temel adres: https://proxysorgula.tr. API yolları sonda eğik çizgi olmadan yazılır (/api/free-proxies), sayfa yolları eğik çizgiyle biter.
• Yanıtlar UTF-8 JSON (veya format=txt ile düz metin) olarak döner. CORS başlığı gönderilmez; tarayıcıdan başka bir kaynaktan çağırmak yerine sunucu tarafında çağırın.
• Hatalar { "error": { "code": "...", "message": "..." } } biçimindedir; message Türkçedir, code makine tarafından okunur.
• İstekler IP adresi başına hız sınırına tabidir. 429 aldığınızda Retry-After başlığındaki saniye kadar bekleyin.
• Adil kullanım: listeyi dakikada bir değil, en fazla birkaç dakikada bir çekin. Kaynak listeler yaklaşık 30 dakikada bir yenilenir, daha sık sorgulamak aynı veriyi getirir.

GET /api/free-proxies

Ücretsiz proxy listesi sayfasının kullandığı uçtur. Kamuya açık kaynaklardan derlenen kayıtları, bizim doğrulama sonuçlarımızla birlikte döndürür. Doğrulanmamış alanlar null gelir; ölçülmeyen değer uydurulmaz.

Yanıt biçimi (JSON)

{
  "data": [
    {
      "id": "socks5://203.0.113.10:1080",
      "ip": "203.0.113.10",
      "port": 1080,
      "protocol": "socks5",
      "ipVersion": 4,
      "country": "DE",
      "countrySource": "geoip",
      "status": "working",
      "latencyMs": 412,
      "lastChecked": "2026-10-30T09:12:44.000Z",
      "sources": ["kaynak-a"],
      "anonymity": null
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1 },
  "meta": {
    "updatedAt": "2026-10-30T09:30:00.000Z",
    "stale": false,
    "sources": [],
    "counts": { "total": 1, "working": 1, "dead": 0, "unverified": 0, "byProtocol": { "http": 0, "https": 0, "socks4": 0, "socks5": 1 } },
    "validation": { "lastRunAt": "2026-10-30T09:30:00.000Z", "tested": 1, "working": 1 },
    "disclaimer": "…"
  }
}

• latencyMs ve lastChecked yalnızca bizim doğrulamamızdan gelir; kayıt hiç doğrulanmadıysa null olur.
• anonymity kaynağın bildirdiği değerdir, biz doğrulamadık. Anonimliği ölçmek için proxy kontrol aracını kullanın.
• meta.updatedAt null ise henüz anlık görüntü oluşmamıştır; data boş gelir. meta.stale verinin beklenenden eski olduğunu gösterir.
• Başarılı yanıtlar Cache-Control: public, s-maxage=30, stale-while-revalidate=60 ile gelir.

Düz metin dışa aktarma

format=txt her satıra bir kayıt yazar. protocol belirtilirse satırlar IP:PORT, belirtilmezse protokol://IP:PORT biçimindedir. status verilmezse yalnızca working kayıtlar listelenir. Dışa aktarma ayrıca daha düşük bir hız sınırına tabidir.

curl -s "https://proxysorgula.tr/api/free-proxies?protocol=socks5&format=txt&limit=100" -o socks5.txt

# JSON, Almanya'daki çalışan HTTP proxy'ler, gecikmeye göre
curl -s "https://proxysorgula.tr/api/free-proxies?protocol=http&country=DE&status=working&sort=latency&limit=20"

const url = new URL('https://proxysorgula.tr/api/free-proxies');
url.searchParams.set('protocol', 'socks5');
url.searchParams.set('status', 'working');
url.searchParams.set('maxLatency', '1500');
url.searchParams.set('limit', '50');

const res = await fetch(url, { headers: { accept: 'application/json' } });
if (res.status === 429) {
  const wait = Number(res.headers.get('retry-after') ?? '30');
  throw new Error(`Hız sınırı: ${wait} sn sonra tekrar deneyin`);
}
if (!res.ok) throw new Error((await res.json()).error.message);

const { data, meta } = await res.json();
console.log(meta.updatedAt, data.map((p) => `${p.ip}:${p.port}`));

import requests

r = requests.get(
    "https://proxysorgula.tr/api/free-proxies",
    params={"protocol": "http", "status": "working", "sort": "latency", "limit": 25},
    timeout=15,
)
r.raise_for_status()
for p in r.json()["data"]:
    print(f"{p['ip']}:{p['port']}", p["latencyMs"], p["country"])

POST /api/proxy-check

Proxy kontrol sayfasının kullandığı uçtur. Verdiğiniz proxy'ye bizim sunucumuzdan bağlanır ve ölçülen sonucu döndürür. Uç, açık bir röle veya SSRF aracı olmasın diye sıkı korunur: yalnızca genel (public) adreslere bağlanır, yalnızca bizim belirlediğimiz test adreslerine istek gönderir ve her istek bir iş kanıtı (proof of work) ister.

İş kanıtı (proof of work) akışı

1. 1

   Görev al

   GET /api/challenge çağrısı { token, bits, expiresAt } döndürür. Görev IP adresinize bağlıdır, yaklaşık iki dakika geçerlidir ve tek kullanımlıktır.

2. 2

   Nonce bul

   SHA-256(token + ":" + nonce) özetinin baştaki sıfır bit sayısı en az bits olana kadar nonce değerini artırın. nonce 1–20 karakterlik küçük harf/rakam dizisi olmalıdır.

3. 3

   İstek gönder

   POST /api/proxy-check gövdesine challenge: { token, nonce } ekleyin. Hızlı art arda görev isteyen istemcilere daha zor görev verilir.

import { createHash } from 'node:crypto';

const BASE = 'https://proxysorgula.tr';

function leadingZeroBits(digest) {
  let bits = 0;
  for (const byte of digest) {
    if (byte === 0) { bits += 8; continue; }
    return bits + Math.clz32(byte) - 24;
  }
  return bits;
}

function solve({ token, bits }) {
  for (let n = 0; ; n++) {
    const nonce = n.toString(36);
    const digest = createHash('sha256').update(`${token}:${nonce}`).digest();
    if (leadingZeroBits(digest) >= bits) return nonce;
  }
}

const task = await (await fetch(`${BASE}/api/challenge`)).json();
const res = await fetch(`${BASE}/api/proxy-check`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    host: '203.0.113.10',
    port: 8080,
    protocol: 'http',
    challenge: { token: task.token, nonce: solve(task) },
  }),
});
console.log(res.status, await res.json());

Yanıt, ölçülen alanları içeren bir sonuç nesnesidir: status (working, connect_failed, auth_required, timeout, unsupported, unverified), timings, connectionMs, varsa capabilities, exit ve anonymity. Bir alan yalnızca gerçekten ölçüldüyse bulunur. Accept: application/x-ndjson gönderirseniz aşamalar (resolve, connect, tls, handshake, auth, request) satır satır akıtılır ve son satır sonuçtur.

GET /api/echo

İsteğin sunucuya ulaştığı haliyle başlıklarını döndürür: { ip, receivedAt, headers }. Bir proxy üzerinden çağırdığınızda proxy'nin Via, X-Forwarded-For gibi başlıkları ekleyip eklemediğini görürsünüz; kontrol aracımız anonimlik seviyesini bu uçla ölçer. cookie, authorization ve iç başlıklar yanıttan çıkarılır. Yanıt hiçbir zaman önbelleğe alınmaz.

curl -s -x http://KULLANICI:[email protected]:8080 "http://proxysorgula.tr/api/echo"

Kullanım koşulları ve sorumluluk

• Yalnızca kendi sistemlerinizi veya izinli olduğunuz proxy'leri test edin. Kontrol aracını port tarama, saldırı veya yük testi için kullanmak yasaktır; kötüye kullanım tespit edilirse erişim kısıtlanır.
• Ücretsiz liste herkese açık kaynaklardan derlenir; çalışırlık ve güvenlik garantisi yoktur. Ayrıntı için ücretsiz proxy kullanmanın riskleri yazısına bakın.
• API için SDK, anahtar veya hesap sistemi yoktur. Ticari proxy ürünlerimizin API'si bu sitede sunulmaz; ürünler saglamproxy.com üzerinden satılır.