Single-file Python CLI that resolves a hostname to an IP and queries ipinfo.io for geolocation and ASN data. Can print the result for a single host or batch-process a list of hosts into a CSV file.
- Stdlib only — no third-party dependencies.
- SSRF-safe: refuses to look up loopback, private, link-local, multicast, reserved, or unspecified addresses.
- HTTPS to ipinfo.io with verified TLS and a configurable timeout.
- Batch mode continues on per-host failures and writes a properly quoted
;-delimited CSV via the stdlibcsvmodule.
- Python 3.10 or newer (uses
dict[str, Any]andlist[str] | None).
Clone the repo and run the script directly — no dependencies to install.
git clone <repo-url> geoip
cd geoip
python geoip.py --helpA .venv/ directory is included for convenience if you want to add tooling
(black, ruff, pytest). Activate it before installing anything:
# Windows
.venv/Scripts/activate
# Linux / macOS
source .venv/bin/activatePrints each ipinfo field on its own line and exits 0 on success, 1 on
failure.
python geoip.py 8.8.8.8
python geoip.py dns.googleExample output:
ip: 8.8.8.8
hostname: dns.google
city: Mountain View
region: California
country: US
loc: 38.0088,-122.1175
org: AS15169 Google LLC
postal: 94043
timezone: America/Los_Angeles
Reads one host per line from FILE and appends host;ip;org rows to the
output CSV. Exits 0 when every host succeeds, 2 when at least one fails
(the batch is not aborted — failing hosts are logged and skipped).
python geoip.py -f domains.txt
python geoip.py -f domains.txt -o out.csv --timeout 5The output file is opened in append mode, so re-running duplicates rows. Truncate the file first for a clean rebuild:
: > data.csv && python geoip.py -f domains.txtusage: geoip.py [-h] [-f FILE] [-o OUTPUT] [--timeout TIMEOUT] [host]
positional arguments:
host hostname to resolve and look up
options:
-h, --help show this help message and exit
-f FILE, --file FILE batch mode: read hostnames one per line from FILE
-o OUTPUT, --output OUTPUT
CSV output path for batch mode (default: ./data.csv)
--timeout TIMEOUT HTTP timeout in seconds (default: 10.0)
Exactly one of host or -f/--file must be provided.
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Single-host lookup failed (DNS, SSRF guard, network, TLS) |
| 2 | Batch finished with at least one failed host, or bad usage |
None. The script requires no configuration beyond its CLI flags. ipinfo.io is queried without a token, so the free unauthenticated quota applies (~50k requests/month).
- The resolved IP is validated with
ipaddress.ip_addressand rejected if the address is private, loopback, link-local, multicast, reserved, or unspecified. This prevents DNS-rebinding or SSRF via attacker-controlled hostnames. - The
orgfield written to CSV is prefixed with'when it begins with= + - @to neutralize spreadsheet-formula injection. - All HTTP calls use
https://withssl.create_default_context().