cache_places/prompt

Paste into Claude Code, Cursor, Copilot, Codex — any coding agent. Replace <I'll paste when you ask> with your own CACHE_PLACES_API_KEY when the agent asks. Not a Go project? The prompt also covers calling the x-api-key HTTP API directly from any language.

Integrate the `cache_places` Go client into this project. It's a cached
front for Google Places Autocomplete + GetPlace.

Service URL:  https://cache-places.dimitri.land
Module path:  github.com/ethanquix/autocomplete_places
Full docs:    README.md at the repo root — it has an "AI agent
              guide" section written for you. READ IT before you start.

Setup steps:

1. Install:

     go get github.com/ethanquix/autocomplete_places@latest
     go mod tidy

2. Import and use:

     import cache_places "github.com/ethanquix/autocomplete_places"

     c := cache_places.New(
         os.Getenv("CACHE_PLACES_URL"),      // https://cache-places.dimitri.land
         os.Getenv("CACHE_PLACES_API_KEY"),  // I'll provide — do NOT hardcode
     )

3. Pick the usage pattern:
   - Already have a place_id  →  c.GetPlace(ctx, id, cache_places.WithGetPlaceUserID(userID))
   - Search-as-you-type       →  sess := c.NewSession()
                                  sess.Autocomplete(ctx, keystroke, cache_places.WithUserID(userID))
                                  sess.GetPlace(ctx, picked, cache_places.WithGetPlaceUserID(userID))

   WHEN POSSIBLE, ALWAYS PASS user_id. It's an opaque string — whatever
   identifies the current end-user on this side (internal id, UUID,
   email). Thread it through from whatever auth/session plumbing the
   project already has. It enables per-user usage analytics via
   GetUsage and costs nothing. Only omit it if there genuinely is no
   user (e.g. a pre-login public search box). Never invent a fake id
   to fill the field. If the call site has no notion of "current user"
   yet, add it — don't silently drop the requirement.

4. Read the "Do NOT do these things" list in README.md before
   finishing. Non-negotiable: don't fall back to Google directly,
   don't rotate session tokens per keystroke, don't double-cache,
   don't swallow ErrNotFound, don't skip user_id when one is available.

PRICING — how you spend my money:
   You are billed per session token you mint, NOT per uncached call.
   A GetPlace cache hit is free, but it does not refund the
   Autocomplete session that produced the place_id. Autocomplete is
   ~$0.017/session, GetPlace ~$0.020 (free on cache hit), SearchNearby
   ~$0.035 (free on cache hit). Cost scales with how many times you
   call Autocomplete — nothing else.

BATCH / BULK JOBS — if you're enriching a fixed list (a CSV, a column
of place_ids), not serving a live human typing, these are
non-negotiable:
   - If you already have a place_id, call GetPlace directly. NEVER use
     Autocomplete to "look up" a place you can already address by id —
     that's a paid session for free-from-cache data.
   - Save the raw GetPlace/SearchNearby JSON to disk on first fetch.
     Do ALL reformatting/column-splitting/CSV shaping offline against
     those files. Reformatting is never a reason to re-hit the API.
   - Validate parsing on 1–2 items BEFORE fanning out to N. A parse
     bug found after sweeping 70 rows costs a 70-row re-sweep.
   - If a few rows are wrong, patch only those rows. Never re-run the
     whole sweep to fix a handful — it re-bills the ones already right.
   - Clean the input first: strip CRLF (\r) and trailing whitespace
     before string-matching. A stray \r from a Windows CSV breaks
     comparisons and sends you re-sweeping to chase a non-API bug.
   Doing a 70-place sweep once is ~$1.20; running it five times to
   chase a local formatting bug is ~$6 for the same output. The API
   can't tell you already paid — that discipline is yours.

ENVIRONMENT — do not load-test against prod. This key bills the same
SKUs whether the caller is a local dev instance or production. If you
need to exercise the integration, use a small deliberate sample, not a
repeated full sweep.

Not a Go project? Query the HTTP API directly:

   The service speaks Connect RPC, which is just HTTP POST + JSON. Any
   language can call it with a plain HTTP client. Same auth, same
   caching, same per-user analytics as the Go client.

   Base URL:  https://cache-places.dimitri.land
   Auth:      send your key in the  x-api-key  header on EVERY request
   Body:      Content-Type: application/json

   Autocomplete (search-as-you-type):
     POST https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/Autocomplete
     {"input": "san fr",
      "session_token": "<a UUID you mint when the user starts typing>",
      "user_id": "<your end-user id>"}

     When you know the user's GPS position, add it. origin_lat +
     origin_lng make every suggestion carry distance_meters (read the
     has_distance flag, not distance_meters == 0). An origin ONLY
     measures — on its own it does not change which places come back,
     because Google then falls back to biasing on the server's IP
     (us-east1). Always pair it with one of these:
       radius_meters       soft preference circle, not a filter
       max_distance_meters hard cap, exact, nothing farther returned
       rank_by_distance    sort nearest-first instead of by relevance
     The last two need a non-zero origin or the call is
     invalid_argument. max_distance_meters supersedes radius_meters
     (Google rejects a request carrying both). None of this costs
     extra: it rides inside the same billable session.

   GetPlace (resolve a picked place_id to full place details):
     POST https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/GetPlace
     {"place_id": "<place_id from an Autocomplete suggestion>",
      "session_token": "<the SAME UUID from the Autocomplete calls>",
      "user_id": "<your end-user id>"}

   curl, end to end (CACHE_PLACES_URL = https://cache-places.dimitri.land):
     SESSION=$(uuidgen)
     curl -X POST "$CACHE_PLACES_URL/cache_places.pb_places.RpcPlaces/Autocomplete" \
       -H "Content-Type: application/json" \
       -H "x-api-key: $CACHE_PLACES_API_KEY" \
       -d "{\"input\":\"san fr\",\"session_token\":\"$SESSION\",\"user_id\":\"u_123\"}"

     curl -X POST "$CACHE_PLACES_URL/cache_places.pb_places.RpcPlaces/GetPlace" \
       -H "Content-Type: application/json" \
       -H "x-api-key: $CACHE_PLACES_API_KEY" \
       -d "{\"place_id\":\"PLACE_ID_HERE\",\"session_token\":\"$SESSION\",\"user_id\":\"u_123\"}"

   The session model is identical to the Go client: mint ONE
   session_token (a UUID) when the user starts typing, reuse it for
   every Autocomplete keystroke in that search AND the final GetPlace,
   then discard it. One session is one billable lookup. Never rotate
   the token per keystroke. Always pass user_id (see step 3) unless
   there genuinely is no current user.

   A 401 with {"code":"unauthenticated"} means the key is missing or
   invalid: stop and ask for CACHE_PLACES_API_KEY, do not retry with a
   guessed value.

Env vars I'll set:
   CACHE_PLACES_URL=https://cache-places.dimitri.land
   CACHE_PLACES_API_KEY=<I'll paste when you ask>

If CACHE_PLACES_API_KEY isn't in my shell yet, stop and ask — don't
invent one, don't use a placeholder string, don't comment it out.