03_browse_residential_locations.py

"""
Browse residential targeting locations: countries → regions → cities.

The codes returned here are what you pass to build_residential_username().
Note: codes can contain underscores (e.g. 'baden_wurttemberg'); the proxy
username uses dashes — the builder handles the conversion automatically.
"""
from proxyshard import ProxyshardClient


def main() -> None:
    client = ProxyshardClient()
    proxy_type = "premium"

    countries = client.residential_countries(proxy_type=proxy_type)
    print(f"=== Countries ({len(countries)}) — first 10 ===")
    for c in countries[:10]:
        print(f"  {c['code']:6}  {c['name']}")

    print(f"\n=== Regions for Germany (DE) ===")
    regions = client.residential_regions("DE", proxy_type=proxy_type)
    for r in regions[:5]:
        print(f"  {r['code']:25}  {r['name']}")

    print(f"\n=== Cities in DE / Berlin ===")
    cities = client.residential_cities("DE", "berlin", proxy_type=proxy_type)
    for city in cities[:5]:
        print(f"  {city['code']:25}  {city['name']}")


if __name__ == "__main__":
    main()