proxywhirl.geo

IP Geolocation utilities for proxy country lookup.

Uses MaxMind GeoLite2-Country database for fast, offline lookups. Falls back to ip-api.com batch API if database not available.

Functions

batch_geolocate(ips[, batch_size, max_batches, db_path])

Geolocate IPs using best available method.

enrich_proxies_with_geo(proxies, geo_data)

Add country info to proxy dictionaries.

geolocate_with_api(ips[, batch_size, max_batches])

Batch geolocate IPs using ip-api.com (fallback).

geolocate_with_database(ips, db_path)

Geolocate IPs using local GeoLite2 database.

Module Contents

async proxywhirl.geo.batch_geolocate(ips, batch_size=100, max_batches=50, db_path=None)[source]

Geolocate IPs using best available method.

Tries in order: 1. Local GeoLite2 database (fast, no rate limits) 2. ip-api.com batch API (fallback, rate limited)

Parameters:

  • ips (list[str]) – List of IP addresses to lookup

  • batch_size (int) – Number of IPs per API batch

  • max_batches (int) – Maximum API batches to process

  • db_path (pathlib.Path | None) – Optional explicit path to GeoLite2 database

Returns:

Mapping of IP to geo info with country and countryCode keys.

Return type:

dict[str, dict[str, str]]

proxywhirl.geo.enrich_proxies_with_geo(proxies, geo_data)[source]

Add country info to proxy dictionaries.

Parameters:

  • proxies (list[dict[str, Any]]) – List of proxy dictionaries with ‘ip’ field

  • geo_data (dict[str, dict[str, str]]) – Geo lookup results from batch_geolocate

Returns:

Proxies with country and country_code fields added

Return type:

list[dict[str, Any]]

async proxywhirl.geo.geolocate_with_api(ips, batch_size=100, max_batches=50)[source]

Batch geolocate IPs using ip-api.com (fallback).

Parameters:

  • ips (list[str]) – List of IP addresses to lookup

  • batch_size (int) – Number of IPs per batch (max 100 for ip-api.com)

  • max_batches (int) – Maximum number of batches to process

Returns:

Mapping of IP to geo info with country and countryCode keys.

Return type:

dict[str, dict[str, str]]

proxywhirl.geo.geolocate_with_database(ips, db_path)[source]

Geolocate IPs using local GeoLite2 database.

Parameters:

  • ips (list[str]) – List of IP addresses to lookup

  • db_path (pathlib.Path) – Path to GeoLite2-Country.mmdb file

Returns:

Mapping of IP to geo info with country and countryCode keys.

Return type:

dict[str, dict[str, str]]