Drop-in widget

All-in-one

Drop in one element and one script. Every element with data-goggle-key is mounted automatically, rendering search + map + directions/transit. Use a publishable (pk) key locked to your origins.

<div data-goggle-key="gk_live_pk_..." data-goggle-mode="both"></div>
<script src="https://www.goggleplaces.com/widget/v1/widget.js" async></script>

The search box is powered by unified /search, so it finds businesses (hotels, restaurants, EV charge points) as well as postcodes, towns and landmarks — and route endpoints can be any of them. The map supports category POI toggles (restaurants, pubs, hotels, EV charging, transport…).

Options (data-attributes): data-goggle-mode = both | directions | search; data-goggle-center = "lng,lat,zoom"; data-goggle-api and data-goggle-tiles to point at a specific deployment.

Composable web components

The same script also registers web components, so you can build your own layout and wire them together with events.

<goggle-search id="s" api-key="gk_live_pk_..." mode="all"></goggle-search>
<goggle-map id="m" api-key="gk_live_pk_..." center="-0.1278,51.5074,11" height="400px"></goggle-map>
<goggle-directions api-key="gk_live_pk_..."></goggle-directions>

<script>
  // fly the map to whatever the search box selects
  s.addEventListener("goggle-select", (e) => m.map.flyTo({ center: [e.detail.lon, e.detail.lat], zoom: 13 }));
</script>

<goggle-search> takes mode = all (default, blend) | addresses (postcodes/towns/landmarks) | places (businesses only) and emits goggle-select with { name, lat, lon, type }. <goggle-map> exposes .map (the MapLibre instance) and emits goggle-ready with { map }. <goggle-directions> is the full route planner.

Securing the widget (restricted keys)

A widget key lives in the browser, so it can be read — restrict it so it can’t be abused. Always use a publishable (pk) key, never a secret key, and lock it two ways: an origin allow-list stops other sites using it, and scopes cap what it can do even if someone lifts it from your page. Origin-lock answers "who can use this key"; scope answers "what can it do" — you want both.

Give the key only the scopes the widget uses: a search + map widget needs "predict" (powers /search) and "tiles"; add "directions" only for the route planner (mode both/directions). That way a lifted key can’t be turned into a free routing API. Per-plan rate limits and monthly quotas are the final cost cap. Mint scoped, origin-locked keys in the dashboard.

search + map widget   → scopes: predict, tiles
route-planner widget  → scopes: predict, tiles, directions
origin allow-list     → https://yourapp.com, https://*.yourapp.com

Attribution

The widget renders OpenStreetMap (ODbL) attribution by default. It must stay visible.