This is a small, typed Python client for the GetFreeProxy API (https://developer.getfreeproxy.com).

The GetFreeProxy API exposes a simple endpoint to fetch public proxy servers:

• GET /v1/proxies — returns a JSON array of proxy objects. Optional query parameters include country, protocol, and page.

Each proxy object contains fields such as ip, port, protocol, proxyUrl, countryCode, anonymity, uptime, and timestamps like lastAliveAt.

• Minimal runtime dependency (httpx).
• Synchronous Client and asynchronous AsyncClient classes with simple query(...) methods.
• Returns a list of Proxy dataclasses (fields mapped to Pythonic names, e.g. country_code).
• Raises typed exceptions on errors: APIError, InvalidAPIKey, NetworkError, TimeoutError, ParseError.

Install from PyPI (when published) or locally in editable mode during development:

pip install freeproxy-python
# or local editable install for development:
pip install -e .[dev]

Sync example:

from freeproxy import Client
client = Client(api_key="YOUR_API_KEY")
proxies = client.query(country="US", protocol="https")
for p in proxies:
 print(p.to_url())
client.close()

Async example:

import asyncio
from freeproxy import AsyncClient
async def main():
 client = AsyncClient(api_key="YOUR_API_KEY")
 proxies = await client.query(country="US")
 for p in proxies:
 print(p.to_url())
 await client.aclose()
asyncio.run(main())

Provide your API key to the client constructor. The client sends Authorization: Bearer <API_KEY> in requests.

• country: ISO 3166-1 alpha-2 country code (e.g. US).
• protocol: proxy protocol filter like http, https, socks5.
• page: pagination page index (integer).

• APIError is raised for non-2xx HTTP responses. The message attempts to surface the API error field when present, otherwise it falls back to the response body.
• InvalidAPIKey is a subclass used when the API returns HTTP 401.
• NetworkError and TimeoutError wrap transport-level failures.

• This client intentionally keeps runtime dependencies minimal and does not implement automatic retries. It also does not stream responses — responses are small (up to ~10 proxies per request).

Run the test suite locally with:

pip install -e .[dev]
pytest -q

MIT