Code Samples

Ready-to-Use Code Examples

Complete code samples in popular programming languages to quickly integrate GetFreeProxy API into your applications. Copy, paste, and customize for your needs.

Try API Playground → View Documentation

Choose Your Language

Select your preferred programming language to see relevant examples

Fetching Proxy Lists

Get available proxies with optional filtering by country and protocol

Python Implementation

requests

import requests
import json

API_KEY = "your-api-key-here"
BASE_URL = "https://api.getfreeproxy.com/v1"

def get_proxies(country=None, protocol=None, page=1):
    """
    Fetch proxy list from GetFreeProxy API
    
    Args:
        country (str): ISO country code (e.g., 'US', 'UK', 'DE')
        protocol (str): Protocol type ('vless', 'ss', 'vmess')
        page (int): Page number for pagination (default: 1)
    
    Returns:
        list: Array of proxy objects with current page data
    """
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Accept': 'application/json'
    }
    
    params = {'page': page}
    if country:
        params['country'] = country
    if protocol:
        params['protocol'] = protocol
    
    try:
        response = requests.get(f"{BASE_URL}/proxies", headers=headers, params=params)
        response.raise_for_status()
        
        data = response.json()
        
        print(f"✓ Found {len(data)} proxies")
        
        return data
        
    except requests.exceptions.HTTPError as e:
        print(f"✗ HTTP Error: {e}")
        if response.status_code == 401:
            print("  Check your API key")
        elif response.status_code == 429:
            print("  Rate limit exceeded")
    except requests.exceptions.RequestException as e:
        print(f"✗ Request failed: {e}")
    
    return None

# Usage examples
if __name__ == "__main__":
    # Get first 10 proxies from any country
    proxies = get_proxies()
    
    # Get US proxies only
    us_proxies = get_proxies(country='US')
    
    # Get Shadowsocks proxies from Germany
    de_ss = get_proxies(country='DE', protocol='ss')
    
    # Get second page of results
    page2 = get_proxies(page=2)
    
    if proxies:
        print("\n🔗 First few proxies:")
        for proxy in proxies[:3]:
            print(f"  {proxy['ip']}:{proxy['port']} ({proxy['countryCode']}) - {proxy['protocol']}")
            print(f"    Anonymity: {proxy['anonymity']}, Uptime: {proxy['uptime']}%, Response: {proxy['responseTime']:.3f}s")
        
        # Example: Filter high-quality proxies
        print("\n⭐ High-quality proxies (>90% uptime, <0.1s response):")
        quality_proxies = [p for p in proxies if p['uptime'] > 90 and p['responseTime'] < 0.1]
        for proxy in quality_proxies[:5]:
            print(f"  {proxy['ip']}:{proxy['port']} - {proxy['anonymity']} - Uptime: {proxy['uptime']}%")

JavaScript Implementation

fetch API

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://api.getfreeproxy.com/v1';

/**
 * Fetch proxy list from GetFreeProxy API
 * @param {Object} options - Request options
 * @param {string} options.country - ISO country code (e.g., 'US', 'UK', 'DE')
 * @param {string} options.protocol - Protocol type ('vless', 'ss', 'vmess')
 * @param {number} options.page - Page number for pagination (default: 1)
 * @returns {Promise} Array of proxy objects or null on error
 */
async function getProxies({ country, protocol, page = 1 } = {}) {
    const params = new URLSearchParams({ page: page.toString() });
    if (country) params.append('country', country);
    if (protocol) params.append('protocol', protocol);
    
    const headers = {
        'Authorization': `Bearer ${API_KEY}`,
        'Accept': 'application/json'
    };
    
    try {
        const response = await fetch(`${BASE_URL}/proxies?${params}`, { headers });
        
        if (!response.ok) {
            if (response.status === 401) {
                throw new Error('Unauthorized - Check your API key');
            } else if (response.status === 429) {
                throw new Error('Rate limit exceeded');
            } else {
                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
            }
        }
        
        const data = await response.json();
        
        console.log(`✓ Found ${data.length} proxies`);
        
        return data;
        
    } catch (error) {
        console.error('✗ Error fetching proxies:', error.message);
        return null;
    }
}

/**
 * Test a specific proxy's connectivity
 * @param {string} ip - Proxy IP address
 * @param {number} port - Proxy port
 * @param {string} protocol - Proxy protocol
 */
async function testProxy(ip, port, protocol) {
    const testData = {
        proxy: { ip, port, protocol },
        target_url: 'https://httpbin.org/ip',
        timeout: 10
    };
    
    try {
        const response = await fetch(`${BASE_URL}/test`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${API_KEY}`,
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(testData)
        });
        
        const result = await response.json();
        
        if (result.working) {
            console.log(`✓ Proxy ${ip}:${port} is working! (${result.response_time}ms)`);
            console.log(`  Anonymity: ${result.anonymity_level}`);
        } else {
            console.log(`✗ Proxy ${ip}:${port} is not working`);
        }
        
        return result;
        
    } catch (error) {
        console.error(`✗ Error testing proxy ${ip}:${port}:`, error.message);
        return null;
    }
}

// Usage examples
(async () => {
    // Get first 10 proxies from any country
    const proxies = await getProxies();
    
    // Get US proxies only
    const usProxies = await getProxies({ country: 'US' });
    
    // Get Shadowsocks proxies from Germany
    const deSs = await getProxies({ country: 'DE', protocol: 'ss' });
    
    // Get second page of results
    const page2 = await getProxies({ page: 2 });
    
    if (proxies && proxies.length > 0) {
        console.log('\n🔗 First few proxies:');
        proxies.slice(0, 3).forEach(proxy => {
            console.log(`  ${proxy.ip}:${proxy.port} (${proxy.countryCode}) - ${proxy.protocol}`);
            console.log(`    Anonymity: ${proxy.anonymity}, Uptime: ${proxy.uptime}%, Response: ${proxy.responseTime.toFixed(3)}s`);
        });
        
        // Example: Filter high-quality proxies
        const qualityProxies = proxies.filter(p => p.uptime > 90 && p.responseTime < 0.1);
        console.log('\n⭐ High-quality proxies (>90% uptime, <0.1s response):');
        qualityProxies.slice(0, 5).forEach(proxy => {
            console.log(`  ${proxy.ip}:${proxy.port} - ${proxy.anonymity} - Uptime: ${proxy.uptime}%`);
        });
    }
})();

Go Implementation

net/http

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "strconv"
    "time"
)

const (
    APIKey  = "your-api-key-here"
    BaseURL = "https://api.getfreeproxy.com/v1"
)

// ProxyResponse represents the API response structure
type ProxyResponse struct {
    Data []Proxy `json:"data"`
}

// Proxy represents individual proxy data
type Proxy struct {
    ID           string  `json:"id"`
    HTTPS        bool    `json:"https"`
    Google       bool    `json:"google"`
    Protocol     string  `json:"protocol"`
    IP           string  `json:"ip"`
    Port         int     `json:"port"`
    User         string  `json:"user"`
    Passwd       string  `json:"passwd"`
    CountryCode  string  `json:"countryCode"`
    Region       string  `json:"region"`
    ASNNumber    string  `json:"asnNumber"`
    ASNName      string  `json:"asnName"`
    Anonymity    string  `json:"anonymity"`
    Uptime       int     `json:"uptime"`
    ResponseTime float64 `json:"responseTime"`
    LastAliveAt  string  `json:"lastAliveAt"`
    ProxyURL     string  `json:"proxyUrl"`
}

// ProxyClient handles API requests
type ProxyClient struct {
    APIKey     string
    HTTPClient *http.Client
}

// NewProxyClient creates a new client instance
func NewProxyClient(apiKey string) *ProxyClient {
    return &ProxyClient{
        APIKey: apiKey,
        HTTPClient: &http.Client{
            Timeout: 30 * time.Second,
        },
    }
}

// GetProxies fetches proxy list with optional filtering
func (c *ProxyClient) GetProxies(country, protocol string, page int) (*ProxyResponse, error) {
    // Build URL with parameters
    u, err := url.Parse(BaseURL + "/proxies")
    if err != nil {
        return nil, fmt.Errorf("invalid base URL: %v", err)
    }
    
    q := u.Query()
    if country != "" {
        q.Set("country", country)
    }
    if protocol != "" {
        q.Set("protocol", protocol)
    }
    if page > 0 {
        q.Set("page", strconv.Itoa(page))
    }
    u.RawQuery = q.Encode()
    
    // Create request
    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
        return nil, fmt.Errorf("failed to create request: %v", err)
    }
    
    req.Header.Set("Authorization", "Bearer "+c.APIKey)
    req.Header.Set("Accept", "application/json")
    
    // Make request
    resp, err := c.HTTPClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("request failed: %v", err)
    }
    defer resp.Body.Close()
    
    // Handle HTTP errors
    if resp.StatusCode != http.StatusOK {
        body, _ := io.ReadAll(resp.Body)
        switch resp.StatusCode {
        case http.StatusUnauthorized:
            return nil, fmt.Errorf("unauthorized - check your API key")
        case http.StatusTooManyRequests:
            return nil, fmt.Errorf("rate limit exceeded")
        default:
            return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
        }
    }
    
    // Parse response
    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read response: %v", err)
    }
    
    var result ProxyResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, fmt.Errorf("failed to decode JSON: %v", err)
    }
    
    fmt.Printf("✓ Found %d proxies\n", len(result.Data))
    
    return &result, nil
}

func main() {
    client := NewProxyClient(APIKey)
    
    // Get first 10 proxies from any country
    proxies, err := client.GetProxies("", "", 1)
    if err != nil {
        fmt.Printf("✗ Error: %v\n", err)
        return
    }
    
    // Get US proxies only  
    usProxies, err := client.GetProxies("US", "", 1)
    if err != nil {
        fmt.Printf("✗ Error fetching US proxies: %v\n", err)
    }
    
    // Get Shadowsocks proxies from Germany
    deSs, err := client.GetProxies("DE", "ss", 1)
    if err != nil {
        fmt.Printf("✗ Error fetching DE HTTPS proxies: %v\n", err)
    }
    
    if len(proxies.Data) > 0 {
        fmt.Println("\n🔗 First few proxies:")
        for i, proxy := range proxies.Data {
            if i >= 3 {
                break
            }
            fmt.Printf("  %s:%d (%s) - %s\n", 
                proxy.IP, proxy.Port, proxy.CountryCode, proxy.Protocol)
            fmt.Printf("    Anonymity: %s, Uptime: %d%%, Response: %.3fs\n", 
                proxy.Anonymity, proxy.Uptime, proxy.ResponseTime)
        }
    }
    
    // Example: Filter high-quality proxies
    fmt.Println("\n⭐ High-quality proxies (>90% uptime, <0.1s response):")
    for _, proxy := range proxies.Data {
        if proxy.Uptime > 90 && proxy.ResponseTime < 0.1 {
            fmt.Printf("  %s:%d - %s - Uptime: %d%%\n", 
                proxy.IP, proxy.Port, proxy.Anonymity, proxy.Uptime)
        }
    }
}

PHP Implementation

cURL

<?php

/**
 * GetFreeProxy API Client
 * 
 * A simple PHP client for interacting with the GetFreeProxy API
 */
class GetFreeProxyClient {
    private string $apiKey;
    private string $baseUrl;
    private int $timeout;
    
    public function __construct(string $apiKey, int $timeout = 30) {
        $this->apiKey = $apiKey;
        $this->baseUrl = 'https://api.getfreeproxy.com/v1';
        $this->timeout = $timeout;
    }
    
    /**
     * Fetch proxy list with optional filtering
     * 
     * @param string|null $country ISO country code (e.g., 'US', 'UK', 'DE')
     * @param string|null $protocol Protocol type ('vless', 'ss', 'vmess')
     * @param int $page Page number for pagination (default: 1)
     * @return array|null Array of proxy objects or null on error
     */
    public function getProxies(?string $country = null, ?string $protocol = null, int $page = 1): ?array {
        $params = ['page' => $page];
        if ($country) $params['country'] = $country;
        if ($protocol) $params['protocol'] = $protocol;
        
        $url = $this->baseUrl . '/proxies?' . http_build_query($params);
        
        $response = $this->makeRequest('GET', $url);
        
        if ($response) {
            echo "✓ Found " . count($response) . " proxies\n";
        }
        
        return $response;
    }
    
    /**
     * Test a specific proxy's connectivity
     * 
     * @param string $ip Proxy IP address
     * @param int $port Proxy port
     * @param string $protocol Proxy protocol
     * @param string $targetUrl URL to test against (default: httpbin.org/ip)
     * @return array|null Test result or null on error
     */
    public function testProxy(string $ip, int $port, string $protocol, string $targetUrl = 'https://httpbin.org/ip'): ?array {
        $data = [
            'proxy' => [
                'ip' => $ip,
                'port' => $port,
                'protocol' => $protocol
            ],
            'target_url' => $targetUrl,
            'timeout' => 10
        ];
        
        $response = $this->makeRequest('POST', $this->baseUrl . '/test', $data);
        
        if ($response) {
            if ($response['working']) {
                echo "✓ Proxy {$ip}:{$port} is working! ({$response['response_time']}ms)\n";
                echo "  Anonymity: {$response['anonymity_level']}\n";
            } else {
                echo "✗ Proxy {$ip}:{$port} is not working\n";
            }
        }
        
        return $response;
    }
    
    /**
     * Make HTTP request to API
     * 
     * @param string $method HTTP method (GET, POST)
     * @param string $url Request URL
     * @param array|null $data Request data for POST requests
     * @return array|null Decoded JSON response or null on error
     */
    private function makeRequest(string $method, string $url, ?array $data = null): ?array {
        $ch = curl_init();
        
        $headers = [
            'Authorization: Bearer ' . $this->apiKey,
            'Accept: application/json'
        ];
        
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => $this->timeout,
            CURLOPT_HTTPHEADER => $headers,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_USERAGENT => 'GetFreeProxy-PHP-Client/1.0'
        ]);
        
        if ($method === 'POST' && $data) {
            $headers[] = 'Content-Type: application/json';
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);
        
        if ($error) {
            echo "✗ cURL Error: {$error}\n";
            return null;
        }
        
        if ($httpCode !== 200) {
            switch ($httpCode) {
                case 401:
                    echo "✗ Unauthorized - Check your API key\n";
                    break;
                case 429:
                    echo "✗ Rate limit exceeded\n";
                    break;
                default:
                    echo "✗ HTTP Error {$httpCode}\n";
            }
            return null;
        }
        
        $decoded = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            echo "✗ JSON Decode Error: " . json_last_error_msg() . "\n";
            return null;
        }
        
        return $decoded;
    }
}

// Usage examples
try {
    $client = new GetFreeProxyClient('your-api-key-here');
    
    // Get first 10 proxies from any country
    $proxies = $client->getProxies();
    
    // Get US proxies only
    $usProxies = $client->getProxies('US');
    
    // Get Shadowsocks proxies from Germany
    $deSs = $client->getProxies('DE', 'ss');
    
    // Get second page of results
    $page2 = $client->getProxies(page: 2);
    
    if ($proxies && !empty($proxies)) {
        echo "\n🔗 First few proxies:\n";
        foreach (array_slice($proxies, 0, 3) as $proxy) {
            echo "  {$proxy['ip']}:{$proxy['port']} ({$proxy['countryCode']}) - {$proxy['protocol']}\n";
            echo "    Anonymity: {$proxy['anonymity']}, Uptime: {$proxy['uptime']}%, Response: " . number_format($proxy['responseTime'], 3) . "s\n";
        }
        
        // Filter high-quality proxies
        echo "\n⭐ High-quality proxies (>90% uptime, <0.1s response):\n";
        foreach ($proxies as $proxy) {
            if ($proxy['uptime'] > 90 && $proxy['responseTime'] < 0.1) {
                echo "  {$proxy['ip']}:{$proxy['port']} - {$proxy['anonymity']} - Uptime: {$proxy['uptime']}%\n";
            }
        }
    }
    
} catch (Exception $e) {
    echo "✗ Error: " . $e->getMessage() . "\n";
}

?>

Quick Reference Guide

Essential API information and common patterns for quick integration

Authentication

Authorization: Bearer YOUR_API_KEY

Include your API key in the Authorization header for all requests

Base URL

https://api.getfreeproxy.com/v1

All API requests should be made to this base URL

Parameters

country - US, UK, DE, etc.

protocol - http, https, socks5

page - Page number (1, 2, 3...)

Common Use Cases

Real-world scenarios and implementation patterns

Web Scraping

Rotate through different proxies to avoid rate limits and blocks

# Rotate proxies for scraping
proxies = get_proxies(country='US')
for i, url in enumerate(urls_to_scrape):
    proxy = proxies['data'][i % len(proxies['data'])]
    proxy_url = f"http://{proxy['ip']}:{proxy['port']}"
    
    response = requests.get(url, proxies={
        'http': proxy_url,
        'https': proxy_url
    })

Geographic Testing

Test how your website appears from different countries

# Test from different regions
countries = ['US', 'UK', 'DE', 'JP']
for country in countries:
    proxies = get_proxies(country=country)
    if proxies['data']:
        proxy = proxies['data'][0]
        # Test your website with this proxy

Load Testing

Distribute API calls across multiple IP addresses

// Load test with distributed IPs
const proxies = await getProxies();
const requests = urls.map((url, i) => {
    const proxy = proxies.data[i % proxies.data.length];
    return fetch(url, { proxy: proxy });
});
await Promise.all(requests);

Uptime Monitoring

Monitor services from multiple global locations

# Monitor from different locations
locations = ['US', 'EU', 'ASIA']
for location in locations:
    proxies = get_proxies(country=location)
    # Check service availability via proxy
    status = check_service_via_proxy(proxies[0])

Ready to Start Building?

Choose your preferred language, copy the code examples, and start integrating our proxy API into your applications today.

Get Your API Key → Try Interactive Playground