import os
import time
import requests

BASE = "https://data.traffic.hereapi.com/v7"
API_KEY = os.environ["HERE_API_KEY"]


class EntitlementError(Exception): ...


def traffic_flow(
    center_lat: float,
    center_lng: float,
    radius_m: int = 2000,
    min_jam_factor: float | None = None,
    location_referencing: str = "shape",   # shape | tmc | olr | none
) -> list[dict]:
    """
    Real-time flow for a circular area.

    `locationReferencing` is MANDATORY. Request ONLY the scheme you can
    actually interpret — asking for `shape` when you only use `olr` returns
    geometry you will parse and discard.

    Use `none` if you only want jam factors and do not need geometry at all.
    """
    params = {
        "in": f"circle:{center_lat},{center_lng};r={radius_m}",
        "locationReferencing": location_referencing,
        "apiKey": API_KEY,
    }
    if min_jam_factor is not None:
        # Server-side filter. Do NOT fetch everything and filter locally.
        params["minJamFactor"] = min_jam_factor

    backoff = 1.0
    for _ in range(3):
        resp = requests.get(f"{BASE}/flow", params=params, timeout=15)
        if resp.status_code == 403:
            raise EntitlementError("Traffic 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("Traffic flow failed after retries")

    out = []
    for item in resp.json().get("results", []):
        flow = item["currentFlow"]
        out.append({
            "street": item["location"].get("description"),
            "length_m": item["location"]["length"],
            "speed_mps": flow.get("speed"),
            "free_flow_mps": flow.get("freeFlow"),
            # 0.0 = free flow. 10.0 = road closed / standstill.
            "jam_factor": flow.get("jamFactor"),
            "traversability": flow.get("traversability"),
        })
    return out


def traffic_incidents(bbox: str, lang: str = "en-US") -> list[dict]:
    """
    Incidents for a bounding box. `bbox:west,south,east,north`

    Flow signals closures via jamFactor. For closures specifically,
    HERE recommends Incidents, not Flow.
    """
    resp = requests.get(
        f"{BASE}/incidents",
        params={
            "in": f"bbox:{bbox}",
            "locationReferencing": "shape",
            "lang": lang,   # descriptions default to the country's language
            "apiKey": API_KEY,
        },
        timeout=15,
    )
    if resp.status_code == 403:
        raise EntitlementError("Traffic not entitled")
    resp.raise_for_status()

    return [
        {
            "id": r["incidentDetails"]["id"],
            "type": r["incidentDetails"]["type"],
            "criticality": r["incidentDetails"]["criticality"],
            "road_closed": r["incidentDetails"]["roadClosed"],
            "start": r["incidentDetails"]["startTime"],
            "end": r["incidentDetails"]["endTime"],
            "description": r["incidentDetails"].get("description", {}).get("value"),
        }
        for r in resp.json().get("results", [])
    ]


if __name__ == "__main__":
    # Only segments with meaningful congestion. Filter server-side.
    jams = traffic_flow(51.50643, -0.12719, radius_m=1000, min_jam_factor=4.0)
    for j in sorted(jams, key=lambda x: -(x["jam_factor"] or 0))[:5]:
        print(f"{j['street']}: jamFactor {j['jam_factor']}")

const BASE = "https://data.traffic.hereapi.com/v7";
const API_KEY = process.env.HERE_API_KEY;

class EntitlementError extends Error {}

export async function trafficFlow(lat, lng, {
  radiusM = 2000,
  minJamFactor,
  locationReferencing = "shape",   // mandatory. use "none" if you skip geometry
} = {}) {
  const params = new URLSearchParams({
    in: `circle:${lat},${lng};r=${radiusM}`,
    locationReferencing,
    apiKey: API_KEY,
  });
  if (minJamFactor != null) params.set("minJamFactor", String(minJamFactor));

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

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

  const { results = [] } = await resp.json();
  return results.map((item) => ({
    street: item.location.description,
    lengthM: item.location.length,
    speedMps: item.currentFlow.speed,
    freeFlowMps: item.currentFlow.freeFlow,
    jamFactor: item.currentFlow.jamFactor,   // 0 free-flow … 10 standstill
    traversability: item.currentFlow.traversability,
  }));
}

# Flow in a 1 km circle. API key auth.
curl -G 'https://data.traffic.hereapi.com/v7/flow' \
  --data-urlencode 'in=circle:51.50643,-0.12719;r=1000' \
  --data-urlencode 'locationReferencing=shape' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Incidents in a bounding box. OAuth Bearer also supported.
curl -H "Authorization: Bearer ${HERE_TOKEN}" \
  'https://data.traffic.hereapi.com/v7/incidents?in=bbox:13.400,52.500,13.405,52.505&locationReferencing=olr'

# Only significant congestion. Filter server-side, not in your app.
curl -G 'https://data.traffic.hereapi.com/v7/flow' \
  --data-urlencode 'in=circle:51.50643,-0.12719;r=1000' \
  --data-urlencode 'locationReferencing=none' \
  --data-urlencode 'minJamFactor=7' \
  --data-urlencode "apiKey=${HERE_API_KEY}"