cache_places/docs

A ConnectRPC proxy in front of Google Places. Every place_id we've seen before comes back from CockroachDB instead of Google — free, fast, deterministic.

Surfaces

Client — Autocomplete

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/Autocomplete" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input": "sohm", "session_token": "<uuid>", "user_id": "user_123"}'

Response

Client — GetPlace

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/GetPlace" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"place_id": "ChIJ...", "session_token": "<uuid>", "user_id": "user_123"}'

Response

Client — FindPlaceID

Resolve one complete query string to a single best-match place_id, or 404. This is the one-shot resolver for server-side work: enriching a list, resolving a name a model produced, deduping. Autocomplete is the other tool, for partial input with a human picking from the list.

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/FindPlaceID" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query": "Eiffel Tower Paris", "origin_lat": 48.8566, "origin_lng": 2.3522, "radius_meters": 20000, "user_id": "user_123"}'

Request

Response

Client — SearchNearby

A GPS point to the places Google sees there, closest first. Answered by a real spatial query (PostGIS ST_DWithin) against the shared place cache, not by a string key, so any reading inside the same building hits the same rows regardless of GPS jitter.

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/SearchNearby" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"lat": 48.8584, "lng": 2.2945, "included_types": ["restaurant"], "user_id": "user_123"}'

Request

Response

Client — ReverseGeocode

A coordinate to the most specific street address Google knows, returned as an address-level place_id (types like street_address or premise). Not a business: use SearchNearby when you want the shop at that corner rather than the corner itself.

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/ReverseGeocode" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"lat": 48.8584, "lng": 2.2945, "user_id": "user_123"}'

Response

Client — GetUsage

Read back your own traffic. Scope is pinned to the x-api-key on the request — you can never observe another tenant's rows. Pass user_id to narrow to one of your end-users; omit it for everything under this key.

# All usage for this API key
curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/GetUsage" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{}'

# Usage for one end-user
curl -X POST "https://cache-places.dimitri.land/cache_places.pb_places.RpcPlaces/GetUsage" \
  -H "x-api-key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"user_id": "user_123"}'

Response

Admin — issue a key

curl -X POST "https://cache-places.dimitri.land/cache_places.pb_api_keys.RpcApiKeys/CreateApiKey?auth_password=$ADMIN_PW" \
  -H 'Content-Type: application/json' \
  -d '{"name": "sidekick_api prod"}'

The response carries two values: key — the private bearer for the x-api-key header, keep it server-side — and public_key (cppk_…), a publishable token safe to embed in browser ?pk= photo-proxy URLs. It authorizes photo resolution only. Photo URLs returned by GetPlace already carry your pk.

Prefer a UI? Create, list, and revoke keys (and browse usage) from the password-gated admin dashboard at /admin.

Go SDK

import cache_places "github.com/ethanquix/autocomplete_places"

c := cache_places.New("https://cache-places.dimitri.land", os.Getenv("CACHE_PLACES_API_KEY"))

// Always pass WithUserID when you have one — unlocks per-user GetUsage.
s   := c.NewSession()
uid := cache_places.WithUserID("user_123")
hits, _ := s.Autocomplete(ctx, "sohm", uid)
res,  _ := s.GetPlace(ctx, hits[0].PlaceID, cache_places.WithGetPlaceUserID("user_123"))

// Complete string to a place_id, for free. Bias it when you can.
// res.Place often arrives populated, and then you are already done.
found, _ := c.FindPlaceID(ctx, "Eiffel Tower Paris",
    cache_places.WithFindBias(48.8566, 2.3522, 20000))

// GPS to the places Google sees there, closest first.
near, _ := c.SearchNearby(ctx, 48.8584, 2.2945, cache_places.WithSearchUserID("user_123"))

// Read your own usage back out.
u, _ := c.GetUsage(ctx, cache_places.WithUsageUserID("user_123"))
fmt.Println(u.TotalRequests, u.CacheHits)

Full integration guide on README.md. Copy-paste brief for AI agents at /prompt.