"""
IPinfo — IP Geolocation Demo
=============================
A minimal, ready-to-run example of looking up location data for an IP.

Get a token (free tier):
    1. Sign up at https://ipinfo.io/signup
    2. Your access token is shown on the dashboard home page; copy it.

Setup:
    pip install requests
    export IPINFO_TOKEN="..."

Run:
    python ipinfo_demo.py
"""

import os
import requests


def lookup(ip: str = "") -> dict:
    """Return geolocation data for an IP (empty string = caller's own IP)."""
    url = f"https://ipinfo.io/{ip}/json" if ip else "https://ipinfo.io/json"
    response = requests.get(url, params={"token": os.environ.get("IPINFO_TOKEN")})
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    data = lookup("8.8.8.8")
    print(f"{data.get('ip')} — {data.get('city')}, {data.get('country')}")