import os
import time
import requests

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

# Below this, treat the result as unverified and route to review.
# Calibrate against your own ground truth — do not port this number.
MIN_QUERY_SCORE = 0.90


class EntitlementError(Exception):
    """403 — valid key, missing product entitlement. Never retry."""


def geocode(address: str, country: str | None = None, retries: int = 3) -> dict | None:
    """
    Forward geocode a free-text address.

    Returns a normalized record, or None if no acceptable match was found.
    Raises EntitlementError on 403 — retrying will never succeed.
    """
    params = {"q": address, "apiKey": API_KEY, "limit": 1}
    if country:
        # ISO 3166-1 alpha-3. Narrows results and reduces ambiguity.
        params["in"] = f"countryCode:{country}"

    backoff = 1.0
    for attempt in range(retries):
        resp = requests.get(HOST, params=params, timeout=10)

        if resp.status_code == 403:
            raise EntitlementError("Key valid, geocoding not entitled")
        if resp.status_code == 429:
            time.sleep(backoff)
            backoff *= 2
            continue
        if resp.status_code >= 500:
            time.sleep(backoff)
            backoff *= 2
            continue

        resp.raise_for_status()
        break
    else:
        raise RuntimeError(f"Geocode failed after {retries} attempts")

    items = resp.json().get("items", [])
    if not items:
        return None  # No match. Not an error.

    item = items[0]
    scoring = item.get("scoring", {})

    return {
        "position": item["position"],           # The address location
        "access": (item.get("access") or [None])[0],  # Road-network entry point
        "label": item["address"]["label"],      # Normalized address
        "result_type": item["resultType"],
        # "PA" = point address (surveyed). "interpolated" = estimated on a segment.
        "house_number_type": item.get("houseNumberType"),
        "query_score": scoring.get("queryScore"),
        "field_score": scoring.get("fieldScore", {}),
        "here_id": item["id"],
        "trusted": scoring.get("queryScore", 0) >= MIN_QUERY_SCORE,
    }


if __name__ == "__main__":
    result = geocode("425 W Randolph St, Chicago, IL", country="USA")
    if result is None:
        print("No match — route to exception queue")
    elif not result["trusted"]:
        print(f"Low confidence {result['query_score']} — review: {result['field_score']}")
    else:
        # Route to `access`, not `position`. See below.
        print(result["access"] or result["position"])

const HOST = "https://geocode.search.hereapi.com/v1/geocode";
const API_KEY = process.env.HERE_API_KEY;
const MIN_QUERY_SCORE = 0.9;

class EntitlementError extends Error {}

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

/**
 * Forward geocode a free-text address.
 * @returns {Promise<object|null>} null when no acceptable match exists.
 */
export async function geocode(address, { country, retries = 3 } = {}) {
  const params = new URLSearchParams({ q: address, apiKey: API_KEY, limit: "1" });
  if (country) params.set("in", `countryCode:${country}`);

  let backoff = 1000;
  let resp;

  for (let attempt = 0; attempt < retries; attempt++) {
    const ctrl = new AbortController();
    const timer = setTimeout(() => ctrl.abort(), 10_000);

    try {
      resp = await fetch(`${HOST}?${params}`, { signal: ctrl.signal });
    } finally {
      clearTimeout(timer);
    }

    if (resp.status === 403) throw new EntitlementError("Geocoding not entitled");
    if (resp.status === 429 || resp.status >= 500) {
      await sleep(backoff + Math.random() * 250); // jitter
      backoff *= 2;
      continue;
    }
    if (!resp.ok) throw new Error(`HERE returned ${resp.status}`);
    break;
  }

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

  const item = items[0];
  const scoring = item.scoring ?? {};

  return {
    position: item.position,
    access: item.access?.[0] ?? null,
    label: item.address.label,
    resultType: item.resultType,
    houseNumberType: item.houseNumberType,
    queryScore: scoring.queryScore,
    fieldScore: scoring.fieldScore ?? {},
    hereId: item.id,
    trusted: (scoring.queryScore ?? 0) >= MIN_QUERY_SCORE,
  };
}

# Free-text query
curl -G 'https://geocode.search.hereapi.com/v1/geocode' \
  --data-urlencode 'q=425 W Randolph St, Chicago, IL' \
  --data-urlencode 'in=countryCode:USA' \
  --data-urlencode 'limit=1' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Structured query — better for validating user input.
# Note: use qq OR q, never both.
curl -G 'https://geocode.search.hereapi.com/v1/geocode' \
  --data-urlencode 'qq=street=W Randolph St;houseNumber=425;city=Chicago;state=IL;country=USA' \
  --data-urlencode "apiKey=${HERE_API_KEY}"