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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Canonical Examples

Static multi-series office map:

{
  "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:

{
  "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:

{
  "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:

{
  "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"
      }
    }
  ]
}