> For the complete documentation index, see [llms.txt](https://docs.carpose.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carpose.de/misc-modules/10_store-map.md).

# Store Map

### Overview <a href="#overview" id="overview"></a>

The `Store Map` component shows every store/location of the account as a marker on a Google Map. Clicking a marker opens an info window with the store's name, address, phone, e-mail and a route-planner link. It complements the [Store List](/misc-modules/04_store-list.md) (all stores as a list) and the [Store](/misc-modules/03_store-item.md) item (one store on its own page).

### Installation <a href="#installation" id="installation"></a>

The component is part of the Carpose application and requires no separate installation. It does, however, load the Google Maps JavaScript API and therefore needs a Google Maps API key of your own.

### Usage <a href="#usage" id="usage"></a>

```html
<div
  data-carpose-component="store-map"
  data-api-key="your-api-key"
  data-google-api-key="your-google-maps-api-key"
></div>
```

### Configuration Attributes <a href="#configuration-attributes" id="configuration-attributes"></a>

| Attribute                | Type   | Default | Description                                                                                                 |
| ------------------------ | ------ | ------- | ----------------------------------------------------------------------------------------------------------- |
| `data-carpose-component` | string | -       | Identifies the component type, must be set to "store-map"                                                   |
| `data-api-key`           | string | -       | API key for authentication with the Carpose backend services. Required for data fetching.                   |
| `data-google-api-key`    | string | -       | Your Google Maps JavaScript API key. Required — without it Google renders an error tile instead of the map. |

### Google Maps API key <a href="#google-maps-api-key" id="google-maps-api-key"></a>

Create the key in the Google Cloud Console with the **Maps JavaScript API** enabled and restrict it to your website's domains (HTTP referrer restriction). A key restricted to other referrers fails with `RefererNotAllowedMapError` in the browser console and shows "This page didn't load Google Maps correctly" in place of the map.

### Consent gate <a href="#consent-gate" id="consent-gate"></a>

Google Maps transfers data to Google and may set cookies, so the component does not load it on its own. It first renders a placeholder with a "Google Maps laden" button, the provider name (Google Ireland Limited), a short notice and a link to Google's privacy policy. Only after the visitor clicks the button are the stores fetched and the map loaded.

The decision is kept for the browser session (`sessionStorage`), so the visitor is not asked again on the next page with a map; it is not persisted beyond the session and no cookie is written by Carposé.

### Features <a href="#features" id="features"></a>

* One marker per store with coordinates; stores without latitude/longitude are skipped
* Map centre and zoom are calculated from the marker bounds, so all stores are visible on load
* Info window with name, address, phone (click-to-call), e-mail (click-to-mail) and a route-planner link that opens Google Maps in a new tab
* Muted, grey-scale map style so the markers stand out
* Emits `carpose-store-select` when a marker is clicked, see [Store and Employee events](/events/07_store-and-employee.md)

### Behavior <a href="#behavior" id="behavior"></a>

1. **Consent**: the placeholder is shown until the visitor accepts, or immediately skipped when consent was already given in this session.
2. **Data Loading**: after consent the component fetches all stores of the account and computes the bounds.
3. **Interaction**: clicking a marker opens its info window and closes any other; the close button dismisses it.

### Notes <a href="#notes" id="notes"></a>

* Store coordinates are maintained in the Carposé administration under Stores; a store without coordinates does not appear on the map but still appears in the list.
* Live demo: [carpose.de/demo/standortkarte](https://carpose.de/demo/standortkarte)