# The click sequence

> What your app calls at each step of using a map, from the first view to an opened record, with what comes back and what is charged at every one of the steps.

- **HTML:** https://offendersearch.app/docs/map/click-sequence
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **Map API reference as markdown:** https://offendersearch.app/docs/map.md

## The sequence

Each row is one thing a person does on your map: what your app calls, what comes back, and what it costs.

| # | The person | Your app calls | We return | Charge |
| --- | --- | --- | --- | --- |
| 1 | Opens the map: a default view, their location, or a typed address. | `viewport` with the box | Clusters, pins or named pins for that zoom. | 1 map request |
| 2 | Pans or zooms. | `viewport` again, once the map settles | The new view. | 1 map request |
| 3 | Hovers a cluster. | Nothing | The count and breakdown are already on the cluster. | Free |
| 4 | Clicks a cluster. | Nothing. Fit the map to the cluster’s `bbox` at its `expansionZoom`. That moves the map, which is step 2. | — | Step 2 |
| 5 | Clicks a pin that has no name yet (zoom 13–14). | Your choice: zoom in (step 2), or open the record (step 8). | — | Step 2 or step 8 |
| 6 | Clicks a named pin. | Nothing. The popup uses the label, housing status and photo flag already on the pin. | — | Free |
| 7 | Clicks a pin that stands for several people at one address, or an approximate-area pin. | `groups/{groupId}` | The people in it, a page at a time: an id and a label each. | 1 map request per page |
| 8 | Clicks “View record”. | `records/{markerId}` | The complete record, with the photo. | 1 record open |
| 9 | Closes the record and opens it again. | `records/{markerId}` with the same id | The same record. | Free |
| 10 | Moves the map, comes back, and opens the same person. | `viewport`, then `records/{newId}` | New ids, and the record. | 1 map request + 1 record open |
| 11 | Shares or bookmarks a record. | Store the `recordRef` from step 8. Later: `records/{recordRef}`. | The record. | 1 record open, then free for 24 hours |
| 12 | Asks to be told when someone moves into this area. | The Monitoring API: `POST /v1/monitors` with a location. | — | The monitoring price |

## The states

From a view to a record: the call and the charge on each step.

```text
[ Map view ]
     |  viewport                        1 map request
     v
[ Clusters ]      zoom 3–12
     |  click: fit bbox at expansionZoom, then viewport
     |                                  1 map request
     v
[ Pins ]          zoom 13–14
     |  zoom in, then viewport          1 map request
     v
[ Named pins ]    zoom 15+
     |  many-people or area pin: groups/{groupId}
     |                                  1 map request per page
     |  pin or list row: records/{markerId}
     |                                  1 record open
     v
[ Record ]        the same marker id again: free
```

## Notes on the steps

- **Step 2: wait for the map to settle.** Call on move end, after a short pause, and cancel the request you no longer need. A drag is then one map request, not one for every frame.
- **Step 2: send `If-None-Match`.** Coming back to a view you already have answers `304`, which is free. See [The viewport request](https://offendersearch.app/docs/map/viewport.md).
- **Step 4: a cluster never traps the user.** `expansionZoom` is the zoom at which it becomes smaller clusters, pins, or one many-people pin.
- **Step 7: the list is paged.** Each page is one map request. Members have labels when the pin came from a named view.
- **Steps 8 to 10: one charge for each person in each map response.** See [Open a record](https://offendersearch.app/docs/map/open-a-record.md).
- **Step 12: an area watch is a different product.** See [location monitoring](https://offendersearch.app/docs/monitoring/location-monitoring.md).

## In code

The three library examples run this whole sequence: [MapLibre](https://offendersearch.app/docs/map/maplibre.md), [Leaflet](https://offendersearch.app/docs/map/leaflet.md), [Google Maps](https://offendersearch.app/docs/map/google-maps.md).

---

## Related

- Previous: [Clusters & markers](https://offendersearch.app/docs/map/clusters-and-markers.md)
- Next: [Open a record](https://offendersearch.app/docs/map/open-a-record.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)