lookup.py

"""Predio — Python example with typed-error handling.

Usage:  PREDIO_API_KEY=pk_... python lookup.py 13077A01800039
Only stdlib (urllib) so it runs anywhere; use requests/httpx in real code if you prefer.
"""
import json
import os
import sys
import urllib.error
import urllib.request

API_KEY = os.environ.get("PREDIO_API_KEY")
if not API_KEY:
    sys.exit("Set PREDIO_API_KEY (free key: https://prediohq.com)")

rc = sys.argv[1] if len(sys.argv) > 1 else "9872023VH5797S0001WX"
req = urllib.request.Request(
    f"https://api.prediohq.com/v1/inmueble/{rc}",
    headers={"x-api-key": API_KEY},
)

try:
    with urllib.request.urlopen(req) as res:
        body = json.load(res)
    prop = body["property"]
    addr = prop.get("address") or {}
    print(f"{addr.get('municipality', '?')} — {prop['class']} / {prop['use']}")
    print(f"Built area: {prop.get('builtAreaM2', 'n/a')} m² · year: {prop.get('yearBuilt', 'n/a')}")
    print(f"Source: {body['source']['provider']} · cached: {body['source']['cached']}")
except urllib.error.HTTPError as e:
    # Every error is JSON with a stable {error: {code, message}} shape — branch on code.
    body = json.load(e)
    code = body.get("error", {}).get("code")
    if code in ("NOT_FOUND", "INVALID_REFERENCE"):   # 404/422 — bad input: don't retry
        sys.exit(f"Bad input (don't retry): {body['error']['message']}")
    if code == "PAYMENT_REQUIRED":                    # 402 — top up, then retrying is safe
        sys.exit(f"Out of credits: {body['error']['message']}")
    if code == "RATE_LIMITED":                        # 429 — back off and retry
        sys.exit(f"Rate limited, retry after: {e.headers.get('retry-after', '?')}s")
    sys.exit(f"Transient ({e.code}): {body.get('error', {}).get('message', 'unknown')}")  # 5xx — retryable