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

# Map Widget

> Display embedded Google Maps at specified latitude/longitude coordinates

The Map Widget is a specialty widget that displays an embedded Google Map at given latitude/longitude coordinates. It is non-interactive apart from zooming in and out.

## Example Code

```json theme={null}
{
  "type": "sheetTemplateWidgets",
  "attributes": {
    "type": "map",
    "label": "Map",
    "equation": [
      {
        "result": "{latitude: latitude, longitude: longitude}",
        "condition": "@default"
      }
    ],
    "referenceId": "map"
  }
}
```

## Parameters

<ParamField path="type" type="string" required>
  Must be "map" - defines the widget type
</ParamField>

<ParamField path="label" type="string" required>
  The name of the widget, shows up as the map title
</ParamField>

<ParamField path="referenceId" type="string" required>
  Unique reference ID of the widget
</ParamField>

<ParamField path="equation" type="Equation Object" required>
  Special equation object where the `"result"` should be of the form `"{latitude: 0.000, longitude: 0.000}"`
</ParamField>

<ParamField path="visibleIf" type="string (equation)" default="true">
  An equation that must result in true/false and can hide the widget if certain conditions are met. If `visibleIf==false`, any fields referencing this field will error
</ParamField>

<ParamField path="hidden" type="boolean">
  Flag for whether the widget should be always hidden from users
</ParamField>

## Coordinate Format

The equation result must provide latitude and longitude coordinates:

```json theme={null}
"equation": [
  {
    "condition": "@default",
    "result": "{latitude: projectDefault(\"latitude\"), longitude: projectDefault(\"longitude\")}"
  }
]
```

### Dynamic Coordinates

You can make coordinates conditional based on user inputs:

```json theme={null}
"equation": [
  {
    "condition": "use_custom_location == true",
    "result": "{latitude: custom_lat, longitude: custom_lon}"
  },
  {
    "condition": "@default", 
    "result": "{latitude: projectDefault(\"latitude\"), longitude: projectDefault(\"longitude\")}"
  }
]
```

## Functionality

<CardGroup cols={2}>
  <Card title="Display Only" icon="map">
    Shows Google Maps embedded view at specified coordinates
  </Card>

  <Card title="Limited Interaction" icon="magnifying-glass">
    Users can only zoom in and out of the map view
  </Card>
</CardGroup>

## Common Use Cases

* **Site Location**: Display project location for wind/seismic data
* **Geographic Context**: Show building location for environmental loads
* **Reference Location**: Display coordinates for code-specific regional parameters
* **GIS Integration**: Visual reference for geospatial data inputs

## Best Practices

<Tip>
  * Ensure latitude and longitude values are valid (lat: -90 to 90, lon: -180 to 180)
  * Use meaningful labels to indicate the purpose of the map
  * Consider making the map conditional if not always relevant
  * Test with different coordinate sources (user input vs project defaults)
  * Provide fallback coordinates for edge cases
</Tip>

## Integration with Project Defaults

The Map Widget commonly integrates with project-level location settings:

```json theme={null}
"result": "{latitude: projectDefault(\"latitude\"), longitude: projectDefault(\"longitude\")}"
```

This allows the map to automatically display the project location set in the project defaults, which is often used for determining regional load parameters and building codes.