> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Locator Widget — Data Processing

> Every network request the embeddable store locator makes, what each one carries, and who receives it.

The store locator embed runs Closient JavaScript on **your** pages. That makes
it your visitors' data, disclosed under your privacy notice — so you need to
know exactly what it sends and where. This page is the factual inventory to
work from when you fill in your own notice or a data processing agreement.

<Info>
  This page describes system behaviour, not legal terms. Closient's own privacy
  policy and terms are published separately at
  [closient.com](https://www.closient.com) and govern our side of the
  relationship.
</Info>

## Requests the widget makes

Everything the widget loads or calls, in the order a visitor triggers it.

| Request                                       | Sent to                      | Carries                                                                                                | When                                                              |
| --------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| Widget script + styles + map library          | **Closient**                 | Standard HTTP request metadata (IP, user agent, referring page)                                        | On page load                                                      |
| `POST /locations/api/v1/public/widget-events` | **Closient**                 | Event name, your publishable key prefix, referring URL, and — on a search — the text the visitor typed | On load, search, and click-through                                |
| `GET /locations/api/v1/public/geo`            | **Closient**                 | Nothing beyond the request itself                                                                      | Only if the visitor denies or ignores the browser location prompt |
| `GET /locations/api/v1/public/geocode`        | **Closient**                 | The address, city, or postal code the visitor typed                                                    | Only when the visitor searches by address                         |
| `GET /locations/api/v1/public/locations`      | **Closient**                 | The search coordinates and radius                                                                      | Once a location is established                                    |
| Map tiles                                     | **OpenStreetMap Foundation** | Standard HTTP request metadata, plus the map area being viewed                                         | Only once a map renders, and only if the map is switched on       |

**Closient is the only party that receives visitor data, with one exception:
map tiles** — and that exception is one you can switch off, with
[`data-map="off"`](#reducing-third-party-exposure-to-zero).

Tile images are fetched by the visitor's browser directly from
[OpenStreetMap](https://www.openstreetmap.org), so while the map is on, the
OpenStreetMap Foundation sees the visitor's IP address and which map area they
are looking at. Under their
[tile usage policy](https://operations.osmfoundation.org/policies/tiles/) they
also publish anonymised, aggregated usage data that includes which websites use
the service. No other third party is contacted — the map library is bundled
into the widget script, and both location lookups run on Closient's servers
rather than in the visitor's browser.

<Note>
  **Why Closient does not proxy tiles for you.** We proxy the geocoder, so the
  obvious question is why not the map as well. The OpenStreetMap tile usage
  policy forbids it: §3.4 rules out "tunnel\[ling] all clients behind a single,
  anonymous identity", which is precisely the property that would make a proxy
  private, and §5 says the Foundation "generally do\[es] not recommend" a caching
  proxy in front of their tiles. A proxy that satisfied the policy would still
  disclose your visitors; one that protected them would breach it. The honest
  options are therefore a tile source you hold your own agreement with, or no
  map — both below.
</Note>

## How location is determined

The widget tries three sources, in order, and stops at the first that works.

<Steps>
  <Step title="Browser geolocation">
    The browser's own location prompt. Precise, and shown to the visitor as an
    explicit permission request by their browser. Closient receives the
    resulting coordinates but never the underlying device signals.
  </Step>

  <Step title="Network-level approximation">
    If the visitor denies or ignores the prompt, the widget asks Closient for
    the approximate location our edge network already derives from the
    connection. This is city-level at best and often less. It happens
    server-side: no third-party geolocation service is involved, and the
    visitor's IP address is not stored or returned.
  </Step>

  <Step title="Address search">
    If neither is available, the visitor types a place. The text is sent to
    Closient, which resolves it to coordinates server-side and caches the
    result. The visitor's browser never contacts the geocoding provider, so
    the provider sees Closient's servers rather than your visitors.
  </Step>
</Steps>

## Cookies and storage

**The widget sets no cookies and writes nothing to `localStorage`,
`sessionStorage`, or IndexedDB.** It holds state in memory for the life of
the page only. Analytics events are attributed to your publishable key, not
to a visitor identifier — there is no cross-site or cross-session tracking,
and consequently nothing for a cookie banner to gate.

Coordinates from the browser's location prompt are used for the search that
requested them and are not persisted.

## What Closient retains

| Data                                          | Retained                                                                                                        |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Widget analytics events (load, search, click) | Written to application logs for usage reporting. Not stored in a database and not linked to a visitor identity. |
| Search text                                   | Appears in those same logs, truncated. Geocoded results are cached by search text, not by visitor.              |
| Search coordinates                            | Used to answer the request. Not persisted.                                                                      |
| IP addresses                                  | Not stored by the widget endpoints.                                                                             |

## Reducing third-party exposure to zero

If your privacy posture rules out any third-party request, the map is the only
thing standing in the way — and `data-map="off"` removes it:

```html theme={null}
<script src="https://www.closient.com/widget/v1/store-locator.js"
        data-api-key="cpk_live_xxx"
        data-map="off"></script>
```

Every row in the request table above then points at Closient, and no map tile
is requested. The widget degrades cleanly: the store list, search, distances,
and click-throughs all work without a map, and the list expands to fill the
space the map would have taken.

The same applies to the iframe embed, via a query parameter:

```
https://www.closient.com/widget/store-locator/?key=cpk_live_xxx&map=off
```

### Keeping a map, on your own terms

If you already hold an agreement with a tile provider — MapTiler, Stadia Maps,
your own tile server — point the widget at it with `data-tile-url` and give the
provider's required attribution in `data-tile-attribution`:

```html theme={null}
<script src="https://www.closient.com/widget/v1/store-locator.js"
        data-api-key="cpk_live_xxx"
        data-tile-url="https://tiles.example.com/{z}/{x}/{y}.png"
        data-tile-attribution="&copy; Example Maps"></script>
```

Visitors then reach a processor you have listed, rather than one you have not.
`data-tile-attribution` is required whenever `data-tile-url` is set: rather than
guess an attribution or quietly fall back to OpenStreetMap — the host you were
configuring your way off — the widget switches the map off and logs the reason
to the browser console. Both attributes are script-embed only; the iframe embed
accepts `map=off` but not a custom tile URL.

## Configuration reference

The embed accepts these attributes. Only `data-map` and `data-tile-url` change
what data is processed, and both only by removing or redirecting the map tile
request.

| Attribute               | Purpose                                                                                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data-api-key`          | Your publishable key (`cpk_…`). Safe to expose — it is read-only and scoped to your organization's locations.                                                                                                                     |
| `data-api-base`         | Closient origin the widget calls. Defaults to wherever the script was served from.                                                                                                                                                |
| `data-theme`            | `light` or `dark`.                                                                                                                                                                                                                |
| `data-radius`           | Search radius.                                                                                                                                                                                                                    |
| `data-unit`             | `km` or `mi`.                                                                                                                                                                                                                     |
| `data-map`              | `on` (default) or `off`. `off` renders the locator with no map and makes the embed entirely first-party. Any other value is treated as `off`, with a console warning — a typo should not leave a third-party request switched on. |
| `data-tile-url`         | Tile source for the map, as a Leaflet `{z}/{x}/{y}` template. Defaults to OpenStreetMap. Requires `data-tile-attribution`.                                                                                                        |
| `data-tile-attribution` | Attribution shown on the map for a custom `data-tile-url`. Required whenever that attribute is set.                                                                                                                               |