# Show Geo Map

`Show_Geo_Map` renders an interactive geo workspace inside chat. Use it for named marker series, route overlays, dense point maps with clustering, and marker-selection workflows where the user should click locations instead of replying in free text.

## When To Use

* Use `Show_Geo_Map` for geographic review of buyer offices, vendor offices, field sites, target facilities, or other point-based location sets.
* Use `Show_Geo_Map` when a route overlay helps explain travel, coverage, or HQ-to-site relationships.
* Turn on `selection` when the user should click markers and send the chosen locations back to chat through `Interaction_State`.
* Turn on `clustering` for dense office, site, or facility maps where point overlap would otherwise make the map unreadable.
* Do not use `Show_Geo_Map` for choropleths, boundary-layer analysis, GeoJSON polygons, or heatmaps in this phase.
* Use `Show_Chart` when the user needs a trend, comparison, or leaderboard rather than a geographic surface.

## Contract

* Required top-level keys:
  * `id`
  * `series`
* Optional top-level keys:
  * `title`
  * `description`
  * `clustering`
  * `viewport`
  * `selection`
  * `legend`
  * `routes`

## Series And Markers

* `series` is a required non-empty array.
* Each series must include:
  * `id`
  * `label`
  * `markers`
* Each marker must include:
  * `id`
  * `lat`
  * `lng`
  * `label`
* Optional marker keys:
  * `subLabel`
  * `tooltip`
  * `detail`
  * `recordRef`
  * `metadata`
  * `style`
* Optional series keys:
  * `color`
  * `style`
* Marker ids must be unique across the entire map so selection state can address them safely.

## `clustering`

* `clustering` is an optional strict object for dense marker sets.
* Supported shape:

```json
{
  "enabled": true,
  "radius": 40,
  "maxZoom": 12,
  "spiderfy": true
}
```

* Clustering applies only to markers, never routes.
* Cluster clicks zoom or spiderfy; clusters are not themselves selectable.

## `viewport`

* `viewport` is an optional strict object.
* Supported shape:

```json
{
  "mode": "center_zoom",
  "center": {"lat": 38.8895, "lng": -77.0353},
  "zoom": 5
}
```

* `mode` values:
  * `fit_all`
  * `center_zoom`
* `center_zoom` requires both `center` and `zoom`.
* `fit_all` auto-fits all markers and routes and does not accept `center` or `zoom`.

## `selection`

* `selection` is an optional strict object.
* Selection is marker-only in this phase.
* When `selection.enabled` is `true`, `Show_Geo_Map` returns interaction fields and writes canonical marker selections, selected record refs, viewport state, and last-event metadata through `Interaction_State`.
* Supported shape:

```json
{
  "enabled": true,
  "mode": "multi",
  "tools": ["click", "box"],
  "allowSelectInView": true,
  "minSelections": 1,
  "maxSelections": 3,
  "helperText": "Select the buyer offices you want to analyze.",
  "submitLabel": "Use selected offices"
}
```

* `mode` values:
  * `single`
  * `multi`
* `tools` values:
  * `click`
  * `box`
* `click` is always required.
* `box` enables Shift-drag box selection on multi-select maps.
* `allowSelectInView` shows a “Select visible” action that replaces the current selection with markers inside the current viewport.

## Marker Styling

* Use `series.style` for semantic defaults and `marker.style` only for per-marker emphasis.
* Supported style shape:

```json
{
  "color": "#2563eb",
  "size": "lg",
  "icon": "circle",
  "opacity": 0.95,
  "strokeColor": "#ffffff",
  "strokeWidth": 2,
  "zIndex": 40
}
```

* Supported `size` values:
  * `sm`
  * `md`
  * `lg`
* Supported `icon` values:
  * `circle`
  * `square`
  * `diamond`
  * `triangle`
  * `star`

## `routes`

* `routes` is an optional array.
* Each route must include:
  * `id`
  * `points`
* Optional route keys:
  * `label`
  * `tooltip`
  * `detail`
  * `style`
* `style` is a strict object like:

```json
{
  "color": "#125475",
  "weight": 3,
  "opacity": 0.9,
  "dash": "dashed"
}
```

## Canonical Examples

Static multi-series office map:

```json
{
  "id": "buyer-and-vendor-map",
  "title": "Buyer And Vendor Offices",
  "series": [
    {
      "id": "buyers",
      "label": "Buyer offices",
      "color": "#2563eb",
      "markers": [
        {"id": "buyer-1", "lat": 38.8831, "lng": -77.0164, "label": "NAVSEA HQ", "subLabel": "Buyer office"}
      ]
    },
    {
      "id": "vendors",
      "label": "Vendor HQs",
      "color": "#0f766e",
      "markers": [
        {"id": "vendor-1", "lat": 39.2904, "lng": -76.6122, "label": "Vendor HQ", "subLabel": "Vendor office"}
      ]
    }
  ]
}
```

Selectable buyer-office map with box select and select-visible:

```json
{
  "id": "select-buyers",
  "title": "Select Buyer Offices",
  "selection": {
    "enabled": true,
    "mode": "multi",
    "tools": ["click", "box"],
    "allowSelectInView": true,
    "minSelections": 1,
    "maxSelections": 3,
    "submitLabel": "Use selected offices"
  },
  "series": [
    {
      "id": "buyers",
      "label": "Buyer offices",
      "markers": [
        {
          "id": "navsea-hq",
          "lat": 38.8831,
          "lng": -77.0164,
          "label": "NAVSEA HQ",
          "tooltip": "NAVSEA HQ • Buyer office",
          "detail": {
            "title": "NAVSEA HQ",
            "description": "Department of the Navy buying office",
            "fields": [
              {"label": "Agency", "value": "Department of the Navy"}
            ]
          },
          "recordRef": {
            "entityType": "federal_office",
            "entityId": "office-navsea-hq"
          }
        }
      ]
    }
  ]
}
```

Clustered styled office map:

```json
{
  "id": "clustered-buyers",
  "title": "Buyer Office Density",
  "clustering": {
    "enabled": true,
    "radius": 40,
    "maxZoom": 12,
    "spiderfy": true
  },
  "series": [
    {
      "id": "buyers",
      "label": "Buyer offices",
      "style": {
        "color": "#2563eb",
        "size": "lg",
        "icon": "circle"
      },
      "markers": [
        {"id": "buyer-1", "lat": 38.8831, "lng": -77.0164, "label": "NAVSEA HQ"},
        {"id": "buyer-2", "lat": 38.8951, "lng": -77.0364, "label": "Fleet Office"},
        {"id": "buyer-3", "lat": 38.9012, "lng": -77.0418, "label": "Logistics Office", "style": {"icon": "star"}}
      ]
    }
  ]
}
```

Route / coverage map:

```json
{
  "id": "coverage-route-map",
  "title": "Coverage Route",
  "viewport": {
    "mode": "fit_all",
    "padding": 40,
    "maxZoom": 8
  },
  "series": [
    {
      "id": "sites",
      "label": "Sites",
      "markers": [
        {"id": "hq", "lat": 38.8831, "lng": -77.0164, "label": "HQ"},
        {"id": "field", "lat": 36.9466, "lng": -76.3307, "label": "Field Office"}
      ]
    }
  ],
  "routes": [
    {
      "id": "hq-to-field",
      "label": "HQ to Field",
      "points": [
        {"lat": 38.8831, "lng": -77.0164},
        {"lat": 36.9466, "lng": -76.3307}
      ],
      "style": {
        "color": "#125475",
        "weight": 4,
        "dash": "dashed"
      }
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/tools/show-geo-map.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.