import os
import requests

DISCOVER = "https://discover.search.hereapi.com/v1/discover"
BROWSE = "https://browse.search.hereapi.com/v1/browse"
LOOKUP = "https://lookup.search.hereapi.com/v1/lookup"
API_KEY = os.environ["HERE_API_KEY"]


class EntitlementError(Exception): ...


def discover(query: str, at: str, limit: int = 10) -> list[dict]:
    """
    Free-text place search. Results ranked by RELEVANCE.

    Use for: a user typed something and wants the best match.
    Do NOT use for: a store finder. The nearest store will not be first.
    """
    resp = requests.get(DISCOVER, params={
        "q": query,
        "at": at,                # "lat,lng" — search context centre
        "limit": limit,
        "apiKey": API_KEY,
    }, timeout=10)

    if resp.status_code == 403:
        raise EntitlementError("Discover not entitled")
    resp.raise_for_status()

    return [
        {
            "title": it["title"],
            "here_id": it["id"],           # ← store this, use /lookup later
            "position": it["position"],
            "distance_m": it.get("distance"),
            "categories": [c["name"] for c in it.get("categories", [])],
        }
        for it in resp.json().get("items", [])
    ]


def browse(at: str, categories: str | None = None,
           radius_m: int = 2000, limit: int = 10) -> list[dict]:
    """
    Category-filtered places, ranked by DISTANCE from `at`.

    Use for: "pharmacies within 2 km", ordered nearest-first.
    """
    params = {"at": at, "limit": limit, "apiKey": API_KEY}
    if categories:
        # HERE category IDs. See the category system reference.
        params["categories"] = categories
    if radius_m:
        params["in"] = f"circle:{at};r={radius_m}"

    resp = requests.get(BROWSE, params=params, timeout=10)
    if resp.status_code == 403:
        raise EntitlementError("Browse not entitled")
    resp.raise_for_status()

    return [
        {
            "title": it["title"],
            "here_id": it["id"],
            "position": it["position"],
            "distance_m": it.get("distance"),   # already sorted ascending
        }
        for it in resp.json().get("items", [])
    ]


def lookup(here_id: str) -> dict:
    """
    Retrieve a known place by HERE ID.

    Re-searching for a place you have already resolved is the POI
    equivalent of not caching geocoding results.
    """
    resp = requests.get(LOOKUP, params={"id": here_id, "apiKey": API_KEY},
                        timeout=10)
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    # Relevance: user typed something
    for p in discover("coffee", at="41.9484,-87.6553", limit=5):
        print(f"{p['title']} ({p['distance_m']}m)")

    # Distance: nearest-first, filtered by category
    for p in browse(at="41.9484,-87.6553", radius_m=1500, limit=5):
        print(f"{p['distance_m']}m — {p['title']}")

# Relevance-ranked free-text search
curl -G 'https://discover.search.hereapi.com/v1/discover' \
  --data-urlencode 'q=restaurant' \
  --data-urlencode 'at=52.5200,13.4050' \
  --data-urlencode 'limit=5' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Distance-ranked, category-filtered, within a radius
curl -G 'https://browse.search.hereapi.com/v1/browse' \
  --data-urlencode 'at=52.5200,13.4050' \
  --data-urlencode 'in=circle:52.5200,13.4050;r=2000' \
  --data-urlencode 'limit=10' \
  --data-urlencode "apiKey=${HERE_API_KEY}"

# Retrieve a known place — no search, no ambiguity
curl -G 'https://lookup.search.hereapi.com/v1/lookup' \
  --data-urlencode 'id=here:pds:place:276u33db-...' \
  --data-urlencode "apiKey=${HERE_API_KEY}"