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

# Point Layer

> Add a point layer to a map showing lat/lng coordinates

```liquid theme={null}
{% map %}
    {% point_layer
        data="store_locations"
        lat="latitude"
        lng="longitude"
        point_title="store_name"
    /%}
{% /map %}
```

## Examples

### Basic Point Map

```liquid theme={null}
{% map %}
    {% point_layer
        data="store_locations"
        lat="latitude"
        lng="longitude"
        point_title="store_name"
    /%}
{% /map %}
```

### Colored by Value

```liquid theme={null}
{% map %}
    {% point_layer
        data="store_sales"
        lat="latitude"
        lng="longitude"
        point_title="store_name"
        color_value="sum(sales)"
        color_palette=["#feedde", "#fdd0a2", "#fdae6b", "#fd8d3c", "#e6550d", "#a63603"]
        color_value_fmt="usd"
    /%}
{% /map %}
```

### Sized by Value

```liquid theme={null}
{% map %}
    {% point_layer
        data="store_locations"
        lat="latitude"
        lng="longitude"
        point_title="store_name"
        size_value="sum(customers)"
    /%}
{% /map %}
```

### Color and Size by Different Values

```liquid theme={null}
{% map %}
    {% point_layer
        data="store_metrics"
        lat="latitude"
        lng="longitude"
        color_value="sum(sales)"
        size_value="sum(customers)"
        color_palette=["#feedde", "#fdd0a2", "#fdae6b", "#fd8d3c", "#e6550d", "#a63603"]
    /%}
{% /map %}
```

### Categorical Coloring

```liquid theme={null}
{% point_layer
    data="locations"
    lat="latitude"
    lng="longitude"
    point_title="name"
    color_value="category"
    color_palette=["#154886", "#45a1bf", "#a5cdee", "#8dacbf", "#85c7c6"]
/%}
```

### Custom Tooltip Fields

```liquid theme={null}
{% map %}
    {% point_layer
        data="power_plants"
        lat="latitude"
        lng="longitude"
        point_title="name"
        point_subtitle="region"
        tooltip_fields=["fuel_type", "capacity_mw", "emissions"]
    /%}
{% /map %}
```

## Attributes

<ResponseField name="data" type="string" required>
  Name of the table to query
</ResponseField>

<ResponseField name="filters" type="array">
  Array of filter IDs to apply
</ResponseField>

<ResponseField name="lat" type="string" required>
  Column name for latitude values
</ResponseField>

<ResponseField name="lng" type="string" required>
  Column name for longitude values
</ResponseField>

<ResponseField name="color_value" type="string">
  Column or expression for coloring points. Numeric values create a gradient scale, categorical values (strings) assign discrete colors from the palette. Examples: "sum(sales)" (numeric gradient), "category" (categorical colors)
</ResponseField>

<ResponseField name="size_value" type="string">
  Column or expression for sizing points (e.g., "sum(customers)"). If not provided, all points will be the same size
</ResponseField>

<ResponseField name="point_title" type="string">
  Column name to use as the point title in tooltips (e.g., "city\_name"). If not provided, lat/lng will be shown
</ResponseField>

<ResponseField name="point_subtitle" type="string">
  Column name to use as the point subtitle in tooltips (e.g., "region"). Displays as a second line with muted text
</ResponseField>

<ResponseField name="shape" type="string" default="circle">
  Shape of the point marker

  **Allowed values:**

  * `circle`
  * `pin`
  * `square`
  * `triangle`
  * `star`
  * `diamond`
</ResponseField>

<ResponseField name="color" type="string">
  Single color for all points (hex, rgb/rgba, or CSS color name)
</ResponseField>

<ResponseField name="color_palette" type="array">
  Array of colors for coloring. For numeric color\_value: creates gradient. For categorical color\_value: assigns discrete colors to categories (cycles if more categories than colors)
</ResponseField>

<ResponseField name="min" type="number">
  Lower bound for the numeric color scale. Values below this clamp to the first color in the palette. Ignored for categorical color\_value. Defaults to the minimum value in the data.
</ResponseField>

<ResponseField name="max" type="number">
  Upper bound for the numeric color scale. Values above this clamp to the last color in the palette. Ignored for categorical color\_value. Defaults to the maximum value in the data.
</ResponseField>

<ResponseField name="midpoint" type="number">
  Anchor a specific value (typically 0) at the middle of a diverging color palette. Requires a numeric color\_value and a color\_palette with 3 or more colors.
</ResponseField>

<ResponseField name="size" type="number" default="6">
  Base size of points in pixels
</ResponseField>

<ResponseField name="size_scale" type="number" default="1">
  Scale multiplier for value-based sizing. Higher values create larger size differences
</ResponseField>

<ResponseField name="tooltip" type="boolean" default="true">
  Show tooltips on hover
</ResponseField>

<ResponseField name="tooltip_fields" type="array">
  Array of SQL expressions for additional fields to show in tooltip (e.g., \["category", "emissions"])
</ResponseField>

<ResponseField name="color_value_fmt" type="string" default="num">
  Format for color values in tooltip. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="size_value_fmt" type="string" default="num">
  Format for size values in tooltip. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="zoom_threshold" type="array">
  Zoom range \[min, max] where this layer is visible (e.g., \[0, 8] shows layer from zoom 0 to 8)
</ResponseField>

<ResponseField name="legend" type="boolean" default="true">
  Show legend for this layer
</ResponseField>

<ResponseField name="legend_label" type="string">
  Custom label for the legend (defaults to table name)
</ResponseField>

<ResponseField name="date_range" type="options group">
  Use date\_range to filter data for specific time periods. Accepts predefined ranges (e.g., "last 12 months"), dynamic ranges (e.g., "Last 90 days"), custom date ranges (e.g., "2020-01-01 to 2023-03-01"), or partial ranges (e.g., "from 2020-01-01", "until 2023-03-01")

  **Example:**

  ```
  date_range={
    range = "today"
    date = "string"
  }
  ```

  **Attributes:**

  * range: `string` - Time period to filter. Use presets like 'last 7 days', dynamic patterns like 'Last 90 days', custom ranges like '2020-01-01 to 2023-03-01', or partial ranges like 'from 2020-01-01'.
    * **Allowed values:**
      * `today`
      * `yesterday`
      * `last 7 days`
      * `last 30 days`
      * `last 3 months`
      * `last 6 months`
      * `last 12 months`
      * `previous week`
      * `previous month`
      * `previous quarter`
      * `previous year`
      * `this week`
      * `this month`
      * `this quarter`
      * `this year`
      * `next week`
      * `next month`
      * `next quarter`
      * `next year`
      * `week to date`
      * `month to date`
      * `quarter to date`
      * `year to date`
      * `all time`
  * date: `string` - Date column to filter on. Required when the data has multiple date columns.
</ResponseField>

<ResponseField name="where" type="string">
  Custom SQL WHERE condition to apply to the query. For date filters, use date\_range instead.
</ResponseField>

<ResponseField name="having" type="string">
  Custom SQL HAVING condition to apply to the query after GROUP BY
</ResponseField>

<ResponseField name="limit" type="number">
  Maximum number of rows to return from the query. Note: When used with tables, limit will disable subtotals to prevent incomplete subtotal rows.
</ResponseField>

<ResponseField name="order" type="string">
  Column name(s) with optional direction (e.g. "column\_name", "column\_name desc")
</ResponseField>

<ResponseField name="qualify" type="string">
  Custom SQL QUALIFY condition to filter windowed results
</ResponseField>

## Allowed Parents

* [map](/components/map)