Google APIs (full setup)
Placard uses one Google Maps Platform API key for both the browser map and server-side Places calls (BYOK — your bill, your quota). Without a key the app still runs; with a key you get the full Places experience.
CRUD, Takeout triage, OSM pin-drop, and MCP work without a Google key. See install.md for Compose / Coolify / Dokploy.
On this page
- What the key unlocks
- Which APIs to enable
- Create a project and key
- Restrict the key
- Put the key in Placard
- Smoke-check
- Cost expectations
What the key unlocks
| Feature | Without key | With key |
|---|---|---|
| Add place by name | OpenStreetMap search by name and area | Places Autocomplete (New), plus OpenStreetMap in Drop pin |
| Click a POI on the Add map | OSM pin only | Maps JavaScript + Place ID |
| Enrichment (hours, phone, website, rating, cover) | Manual / empty | Place Details (New) + photo media |
| Takeout import matching | Exact identifiers, saved-place selection, and pin placement | Text Search / Details for Place IDs |
| Open-now / pick-wheel filters on hours | Only if you typed hours | Hours from Google, computed locally |
OpenStreetMap search uses Photon. A search sends the text you submit to the configured service. Takeout imports do not trigger Photon searches. The default public server is intended for moderate use and can be unavailable. For a private or larger installation, set PLACARD_PHOTON_URL to your Photon search endpoint (including /api/) and restart the app. Photon hosting and usage
Which APIs to enable
In Google Cloud Console → APIs & Services → Library, enable both:
- Places API (New) — server calls: Autocomplete, Place Details, Text Search, photo media
- Maps JavaScript API — browser map on Add place (POI clicks)
You do not need the legacy Places API, Geocoding API, or Directions API for Placard.
Create a project and key
- Open Google Cloud Console and sign in with the Google account that will own billing.
- Create a project (or pick an existing one) — e.g.
placard-home. - Link a billing account. Maps Platform requires billing even when you stay inside the monthly free allowances. Set a budget alert.
- Enable Places API (New) and Maps JavaScript API (links above).
- APIs & Services → Credentials → Create credentials → API key.
- Restrict the key (recommended before any public deploy).
Restrict the key (important)
| Restriction | Recommendation |
|---|---|
| API restrictions | Restrict key to Places API (New) and Maps JavaScript API only |
| Application restrictions | Choose None for the shared key. Website restrictions block server-side Places calls, and server-IP restrictions block the browser map. Under API restrictions, choose Restrict key and select the two APIs above. |
| Quota | Set a daily quota cap on Places (New) and Maps JavaScript so a runaway import cannot surprise-bill you |
One key is intentional: the same value is used in the browser (map) and on the server (Places). Treat it like a secret that is also visible to signed-in users’ browsers — API + quota restrictions are the real guardrails.
Put the key in Placard
Either:
- Set
GOOGLE_MAPS_API_KEY=...in.envand recreate/restart theapp(andworker) containers, or - During first-admin onboarding: Connect Google Maps, or later in Settings → Integrations (admin) — Placard tests the key with a cheap Places call before saving
GOOGLE_MAPS_API_KEY=your-key-hereChanging the env var does not wipe a key already saved in Settings; the UI value wins when present.
Smoke-check the full install
- Settings → Integrations → key saves without error
- Add place → type a restaurant name → pick a suggestion → save
- Place card shows hours / phone when Google has them; cover may appear from Places photos
- Add place map: click a Google POI → preview → add
- Optional: import a small Takeout slice and confirm matches get Place IDs
If Autocomplete works but the map is blank, Maps JavaScript is missing or blocked. If the map works but save/enrich fails, Places API (New) is missing, referrer-restricted, or quota-exhausted.
Cost expectations
Google provides monthly free usage per SKU, shared across projects on a billing account. Place Details, autocomplete sessions, photos, text searches and map loads have different allowances. There is no single shared monthly Maps credit.
Settings → Usage & budget (admin) shows instance-wide local estimates, progress toward each free allowance, request sources, and an optional monthly budget in USD. Costs also appear before imports and bulk refreshes. The standard global pay-as-you-go price catalog is dated in the page; subscriptions, volume discounts, negotiated rates, taxes and currency conversion are not included.
Tracking starts when the budget migration is applied. It cannot see earlier requests or usage by other apps, projects or instances. Changing the key does not reset the ledger. Free allowances are excluded from cost estimates by default; enable “Apply the full monthly free allowances” only if they are available to this instance. The allowance bars always assume no outside usage. Month boundaries use US Pacific time.
Enable “Pause requests” to prevent new Placard requests whose estimated cost would exceed the limit. A zero-dollar limit allows only requests estimated to be free. The web server and worker share the same ledger and serialize budget checks. Cached details do not add usage. Attempts with an unknown billing outcome remain counted conservatively; each retry is another attempt. Autocomplete requests are initially counted individually, then reclassified as free after a successful eligible session completion. Map loads are reserved before mounting the map, so interrupted loads may overcount.
The pause applies only to requests made through Placard. Imports may finish with manually saved, needs-review places when Google requests are blocked; refreshes can finish partially. Increasing the budget permits new requests; failed refresh jobs are not automatically resumed. Google Cloud budget alerts are informational, not a hard spending cap. Use Google Cloud quotas and key restrictions as additional controls, and check the Google billing console for reported costs.
Large Takeout commits and mass refreshes consume allowances quickly. Triage Takeout before import, and prefer per-place refresh.
Next: install.md · MCP