getfreeproxy

A lightweight, zero-dependency TypeScript client library for the GetFreeProxy API. Get free proxies with simple, async/await syntax.

Features

• ✨ Zero Dependencies — Uses only Node.js native https module
• 📦 Dual Package — ESM and CommonJS support
• 🎯 Type Safe — Full TypeScript support with comprehensive types
• 🚀 Simple API — Clean, intuitive interface with async/await
• ⚡ Lightweight — Only 5KB gzipped
• 🛡️ Error Handling — Comprehensive error wrapping
• 🧪 Well Tested — Full test coverage with Jest
• 📝 Well Documented — JSDoc comments and examples

Installation

npm install getfreeproxy

yarn add getfreeproxy

pnpm add getfreeproxy

Quick Start

Basic Usage

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});try{// Get proxies from first pageconstproxies=awaitclient.query();console.log(`Got ${proxies.length} proxies`);// Print first proxy detailsif(proxies.length>0){constproxy=proxies[0];console.log(`${proxy.protocol}://${proxy.ip}:${proxy.port}`);console.log(`Country: ${proxy.countryCode}`);console.log(`Uptime: ${proxy.uptime}%`);}}catch(error){console.error(`API Error: ${errorinstanceofError ? error.message : error}`);}

Query with Filters

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});// Get US proxiesconstusProxies=awaitclient.queryCountry('US');// Get HTTPS proxiesconsthttpsProxies=awaitclient.queryProtocol('https');// Get proxies from page 2constpage2Proxies=awaitclient.queryPage(2);// Combine multiple filtersconstproxies=awaitclient.query({country: 'US',protocol: 'https',page: 1,});

Error Handling

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});try{constproxies=awaitclient.query();}catch(error){console.error(errorinstanceofError ? error.message : error);}

Custom Configuration

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key',timeout: 10000,// 10 secondsbaseUrl: 'https://custom-api.getfreeproxy.com',// Custom API endpoint});constproxies=awaitclient.query();

API Reference

Client

Constructor

newClient(options: ClientOptions)

Options:

• apiKey (required): Your API key from GetFreeProxy
• timeout (optional): Request timeout in milliseconds (default: 30000)
• baseUrl (optional): Custom API base URL (default: https://api.getfreeproxy.com)

Methods

query(params?: QueryParams): Promise<Proxy[]>

Retrieves proxies with optional filters.

Parameters:

• params (optional): Query parameters
  • country: Filter by country code (e.g., 'US', 'GB', 'DE')
  • protocol: Filter by protocol (e.g., 'http', 'https', 'socks5')
  • page: Page number for pagination (default: 1)

Returns: Array of proxy objects

Throws:Error on API or network errors

Example:

constproxies=awaitclient.query({country: 'US',page: 1});

queryCountry(country: string): Promise<Proxy[]>

Convenience method to get proxies by country.

Parameters:

• country: Country code (e.g., 'US', 'GB')

Returns: Array of proxy objects

Example:

constusProxies=awaitclient.queryCountry('US');

queryProtocol(protocol: string): Promise<Proxy[]>

Convenience method to get proxies by protocol.

Parameters:

• protocol: Protocol type (e.g., 'http', 'https', 'socks5')

Returns: Array of proxy objects

Example:

consthttpsProxies=awaitclient.queryProtocol('https');

queryPage(page: number): Promise<Proxy[]>

Convenience method to get proxies from a specific page.

Parameters:

• page: Page number

Returns: Array of proxy objects

Example:

constpage2Proxies=awaitclient.queryPage(2);

Proxy

interfaceProxy{id: string;// Unique identifierprotocol: string;// 'http', 'https', 'socks5', etc.ip: string;// IP addressport: number;// Port numberuser?: string;// Username (if required)passwd?: string;// Password (if required)countryCode: string;// ISO 3166-1 alpha-2 country coderegion?: string;// Region/StateasnNumber?: string;// Autonomous System NumberasnName?: string;// ASN nameanonymity: string;// Anonymity leveluptime: number;// Uptime percentage (0-100)responseTime: number;// Response time in secondslastAliveAt: string;// ISO 8601 timestampproxyUrl: string;// Full proxy URL with credentialshttps: boolean;// Supports HTTPSgoogle: boolean;// Can access Google}

CommonJS Usage

const{ Client }=require('getfreeproxy');constclient=newClient({apiKey: 'your-api-key'});client.query().then(proxies=>{console.log(`Got ${proxies.length} proxies`);}).catch(error=>{console.error(error.message);});

ESM Usage

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});constproxies=awaitclient.query();

Advanced Examples

Iterate Through Pages

import{Client}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});asyncfunctiongetAllProxies(){constallProxies=[];for(letpage=1;page<=100;page++){try{constproxies=awaitclient.queryPage(page);if(proxies.length===0){break;// No more proxies}allProxies.push(...proxies);console.log(`Page ${page}: Got ${proxies.length} proxies`);}catch(error){console.error(`Error on page ${page}:`,error);break;}}returnallProxies;}constproxies=awaitgetAllProxies();

Filter Proxies by Criteria

import{Client,Proxy}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});constproxies=awaitclient.query();// Get only high-uptime proxiesconstreliableProxies=proxies.filter(p=>p.uptime>=95);// Get only proxies that support GoogleconstgoogleProxies=proxies.filter(p=>p.google);// Get only HTTPS-capable proxiesconsthttpsProxies=proxies.filter(p=>p.https);// Combine filtersconstbestProxies=proxies.filter(p=>p.uptime>=95&&p.https&&p.google);

Get Proxy URL with Authentication

import{Client,Proxy}from'getfreeproxy';constclient=newClient({apiKey: 'your-api-key'});constproxies=awaitclient.query();for(constproxyofproxies){// Ready-to-use proxy URL with credentialsconsole.log(`Full URL: ${proxy.proxyUrl}`);// Or build manuallyconstauth=proxy.user&&proxy.passwd ? `${proxy.user}:${proxy.passwd}@` : '';consturl=`${proxy.protocol}://${auth}${proxy.ip}:${proxy.port}`;console.log(`Manual URL: ${url}`);}

Getting Your API Key

Visit GetFreeProxy to get your API key and manage your account.

Testing

npm test# Run tests
npm run test:watch # Watch mode
npm run test:coverage # Coverage report

Development

npm run dev # Watch TypeScript compilation
npm run build # Build for production (ESM + CommonJS)
npm run lint # Run ESLint
npm run format # Format with Prettier

Build Output

The package publishes both ESM and CommonJS formats:

• ESM: dist/esm/index.mjs
• CommonJS: dist/cjs/index.js
• Types: dist/index.d.ts

Browser Compatibility

This package is designed for Node.js only and uses Node.js built-in https module. Browser-based requests to the GetFreeProxy API are not supported due to CORS restrictions - the API does not allow direct calls from web browsers.

For server-side or backend use, use this package. For browser-based applications, consider implementing a proxy server or API gateway to relay requests through your own backend.

Related Projects

• freeproxy-go — Go implementation
• freeproxy-python — Python implementation
• freeproxy-php — PHP implementation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © gfpcom

Support

For API documentation and support, visit GetFreeProxy Developer Docs.