import os
import time
import requests

HOST = "https://revgeocode.search.hereapi.com/v1/revgeocode"
API_KEY = os.environ["HERE_API_KEY"]

# ~5 decimal places ≈ 1 metre. GPS jitter defeats an exact-match cache;
# a vehicle idling at a depot emits hundreds of points within one metre.
COORD_PRECISION = 5

_cache: dict[tuple[float, float], dict] = {}


class EntitlementError(Exception): ...


def _key(lat: float, lng: float) -> tuple[float, float]:
    return (round(lat, COORD_PRECISION), round(lng, COORD_PRECISION))


def reverse_geocode(
    lat: float,
    lng: float,
    types: str | None = None,   # e.g. "area" for city/district only
    radius_m: int | None = None,
) -> dict | None:
    """
    Nearest address to a coordinate.

    Returns None when nothing is nearby. That is a valid outcome.
    """
    k = _key(lat, lng)
    if k in _cache:
        return _cache[k]

    params = {"at": f"{lat},{lng}", "limit": 1, "apiKey": API_KEY}
    if types:
        params["types"] = types
    if radius_m:
        # Spatial filter. Without one, a coordinate in the ocean
        # eventually returns something.
        params["in"] = f"circle:{lat},{lng};r={radius_m}"

    backoff = 1.0
    for _ in range(3):
        resp = requests.get(HOST, params=params, timeout=10)
        if resp.status_code == 403:
            raise EntitlementError("Reverse geocoding not entitled")
        if resp.status_code == 429 or resp.status_code >= 500:
            time.sleep(backoff); backoff *= 2; continue
        resp.raise_for_status()
        break
    else:
        raise RuntimeError("Reverse geocode failed after retries")

    items = resp.json().get("items", [])
    if not items:
        return None

    it = items[0]
    result = {
        "label": it["address"]["label"],
        "result_type": it["resultType"],
        # A NEAREST MATCH, not a truth. In rural areas this may be
        # several hundred metres away, on a different property.
        "distance_m": it.get("distance"),
        "position": it["position"],
        "here_id": it["id"],
    }
    _cache[k] = result
    return result


def multi_reverse_geocode(points: list[dict]) -> list[dict]:
    """
    POST /v1/multi-revgeocode — resolves a LIST in one request.

    If you are looping reverse_geocode() over a batch of detected stops,
    you have made the same mistake as looping routing to build a matrix.
    """
    resp = requests.post(
        "https://revgeocode.search.hereapi.com/v1/multi-revgeocode",
        params={"apiKey": API_KEY},
        json={"items": [
            {"id": p["id"], "at": f"{p['lat']},{p['lng']}"} for p in points
        ]},
        timeout=30,
    )
    if resp.status_code == 403:
        raise EntitlementError("Multi-revgeocode not entitled")
    resp.raise_for_status()
    return resp.json().get("items", [])


# --- The pattern that decides your bill -----------------------------------
def label_detected_stops(stops: list[dict]) -> list[dict]:
    """
    Geocode EVENTS, not packets.

    Instrument the ratio of reverse-geocode calls to detected stops.
    Anything meaningfully above 1 means you are geocoding pings.
    """
    return multi_reverse_geocode(stops)


if __name__ == "__main__":
    # A dispatcher clicked one vehicle. Resolve ONE address.
    print(reverse_geocode(41.88432, -87.63877))

    # Trip closed. Twelve detected stops. ONE request.
    stops = [{"id": f"stop_{i}", "lat": 41.88 + i * 0.01, "lng": -87.63}
             for i in range(12)]
    for item in label_detected_stops(stops):
        print(item.get("id"), item.get("title"))

const HOST = "https://revgeocode.search.hereapi.com/v1/revgeocode";
const MULTI = "https://revgeocode.search.hereapi.com/v1/multi-revgeocode";
const API_KEY = process.env.HERE_API_KEY;
const PRECISION = 5;   // ~1 metre

const cache = new Map();
const key = (lat, lng) => `${lat.toFixed(PRECISION)},${lng.toFixed(PRECISION)}`;

export async function reverseGeocode(lat, lng, { types, radiusM } = {}) {
  const k = key(lat, lng);
  if (cache.has(k)) return cache.get(k);

  const params = new URLSearchParams({ at: `${lat},${lng}`, limit: "1", apiKey: API_KEY });
  if (types) params.set("types", types);
  if (radiusM) params.set("in", `circle:${lat},${lng};r=${radiusM}`);

  const ctrl = new AbortController();
  const t = setTimeout(() => ctrl.abort(), 10_000);
  let resp;
  try { resp = await fetch(`${HOST}?${params}`, { signal: ctrl.signal }); }
  finally { clearTimeout(t); }

  if (resp.status === 403) throw new Error("Reverse geocoding not entitled");
  if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);

  const { items = [] } = await resp.json();
  if (!items.length) return null;

  const result = {
    label: items[0].address.label,
    resultType: items[0].resultType,
    distanceM: items[0].distance,
    position: items[0].position,
    hereId: items[0].id,
  };
  cache.set(k, result);
  return result;
}

/** One request for many coordinates. Do not loop the single endpoint. */
export async function multiReverseGeocode(points) {
  const resp = await fetch(`${MULTI}?apiKey=${API_KEY}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      items: points.map((p) => ({ id: p.id, at: `${p.lat},${p.lng}` })),
    }),
  });
  if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);
  return (await resp.json()).items ?? [];
}

# Nearest address
curl -G 'https://revgeocode.search.hereapi.com/v1/revgeocode' \
  --data-urlencode 'at=41.88432,-87.63877' \
  --data-urlencode 'limit=1' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# City / district only — no street address needed
curl -G 'https://revgeocode.search.hereapi.com/v1/revgeocode' \
  --data-urlencode 'at=53.51246,25.98294' \
  --data-urlencode 'types=area' \
  --data-urlencode 'limit=1' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Many coordinates, one request
curl -X POST "https://revgeocode.search.hereapi.com/v1/multi-revgeocode?apiKey=${HERE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"items":[
        {"id":"stop_1","at":"41.88432,-87.63877"},
        {"id":"stop_2","at":"41.90280,-87.63170"}
      ]}'