A lightweight Go client library for the GetFreeProxy API.
- Simple and clean API interface
- Full support for proxy filtering (country, protocol, pagination)
- Custom HTTP client configuration
- Comprehensive error handling
- Full test coverage
- No external dependencies (uses only Go standard library)
go get github.com/gfpcom/freeproxy-go
- Go 1.25 or later
First, obtain your API key from GetFreeProxy.
package main import ( "fmt" "log" "github.com/gfpcom/freeproxy-go" ) func main() { // Initialize client with your API key c := freeproxy.New("your-api-key") // Get latest 10 proxies proxies, err := c.Query() if err != nil { log.Fatal(err) } for _, proxy := range proxies { fmt.Printf("%s://%s:%d\n", proxy.Protocol, proxy.IP, proxy.Port) } }
func New(apiKey string) *Client
Creates a new GetFreeProxy API client with default HTTP client.
apiKey: Your API key from GetFreeProxy (required)
func NewWith(apiKey string, httpClient *http.Client) *Client
Creates a new GetFreeProxy API client with custom HTTP client.
apiKey: Your API key from GetFreeProxy (required)httpClient: Custom HTTP client. Configure timeouts and other settings before passing.
func (c *Client) Query(options ...QueryOption) ([]Proxy, error)
Retrieves a list of proxies from the API with optional filters using the option pattern.
Parameters:
options: Variable number of query option functions (optional)
Returns:
- Slice of
Proxystructures - Error if the request failed
Example:
// Get proxies with multiple filters proxies, err := c.Query( freeproxy.WithCountry("US"), freeproxy.WithProtocol("http"), freeproxy.WithPage(1), ) if err != nil { log.Fatal(err) }
func (c *Client) QueryCountry(country string) ([]Proxy, error)
Retrieves proxies filtered by country. Convenience method for common use cases.
Parameters:
country: Country code (e.g., "US", "GB", "DE")
Example:
proxies, err := c.QueryCountry("US")
func (c *Client) QueryProtocol(protocol string) ([]Proxy, error)
Retrieves proxies filtered by protocol. Convenience method for common use cases.
Parameters:
protocol: Protocol type (e.g., "http", "https", "socks5")
Example:
proxies, err := c.QueryProtocol("https")
func (c *Client) QueryPage(page int) ([]Proxy, error)
Retrieves proxies from a specific page. Convenience method for pagination.
Parameters:
page: Page number (default: 1)
Example:
proxies, err := c.QueryPage(2)
The API returns a direct JSON array of proxy objects:
type Proxy struct { ID string `json:"id"` 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"` Https bool `json:"https"` Google bool `json:"google"` }
The client returns an Error for all error cases:
proxies, err := c.Query(freeproxy.WithCountry("US")) if err != nil { apiErr, ok := err.(*freeproxy.Error) if ok { fmt.Printf("API Error: %s\n", apiErr.Error()) } }
The error message comes directly from the API's error field in the response.
See the examples/ directory for more complete examples.
proxies, err := c.QueryCountry("US") if err != nil { log.Fatal(err) } for _, proxy := range proxies { fmt.Println(proxy.ProxyUrl) }
proxies, err := c.QueryProtocol("https") if err != nil { log.Fatal(err) }
proxies, err := c.QueryPage(2) if err != nil { log.Fatal(err) }
proxies, err := c.Query( freeproxy.WithCountry("US"), freeproxy.WithProtocol("socks5"), freeproxy.WithPage(1), ) if err != nil { log.Fatal(err) }
for page := 1; page <= 10; page++ { proxies, err := c.QueryPage(page) if err != nil { log.Fatal(err) } if len(proxies) == 0 { break // No more proxies } for _, proxy := range proxies { fmt.Println(proxy.ProxyUrl) } }
Run the test suite:
go test ./...Run tests with coverage:
go test -cover ./...See the LICENSE file for details.
For API documentation and support, visit GetFreeProxy Developer Docs.