> ## 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.

# Area Layer

> Add a choropleth layer to a map

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="name"
        data="state_sales"
        area_id="state"
        value="sum(sales)"
    /%}
{% /map %}
```

## Examples

### US States by Name

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="name"
        data="state_sales"
        area_id="state"
        value="sum(sales)"
    /%}
{% /map %}
```

### US States by Abbreviation

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="abbr"
        data="state_sales"
        area_id="state_abbr"
        value="sum(sales)"
    /%}
{% /map %}
```

### US Counties by State + County

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_counties"
        match_by="state-county"
        data="county_sales"
        area_id="state || '-' || county"
        value="sum(sales)"
    /%}
{% /map %}
```

### US Counties by FIPS

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_counties"
        match_by="fips"
        data="county_sales"
        area_id="state_fips || county_fips"
        value="sum(sales)"
    /%}
{% /map %}
```

### Custom GeoJSON

```liquid theme={null}
{% area_layer
    geojson_url="https://example.com/custom.geojson"
    geojson_id="id"
    data="my_data"
    area_id="region_id"
    value="sum(sales)"
/%}
```

### Diverging Scale Centered at 0

```liquid theme={null}
{% map %}
    {% area_layer
        geography="us_states"
        match_by="abbr"
        data="state_growth"
        area_id="state_abbr"
        value="growth_pct"
        color_palette=["#d73027", "#ffffbf", "#1a9850"]
        min=-100
        max=100
        midpoint=0
    /%}
{% /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="geography" type="string">
  Pre-provided geography (use this OR geojson\_url + geojson\_id)

  **Allowed values:**

  * `us_states`
  * `us_counties`
</ResponseField>

<ResponseField name="match_by" type="string">
  How to match areas. For us\_states: "name", "abbr", or "fips". For us\_counties: "state-county" or "fips".
</ResponseField>

<ResponseField name="geojson_url" type="string">
  URL to custom GeoJSON file (use with geojson\_id for custom maps)
</ResponseField>

<ResponseField name="geojson_id" type="string">
  GeoJSON property to join on. Use a string for single property (e.g., "NAME") or array for composite key (e.g., \["STATE", "COUNTY"]).
</ResponseField>

<ResponseField name="area_id" type="string" required>
  Column name in data that matches geo\_id (e.g., "state\_id")
</ResponseField>

<ResponseField name="value" type="string" required>
  Column or expression for coloring the choropleth (e.g., "sum(sales)")
</ResponseField>

<ResponseField name="color_palette" type="array">
  Array of colors for the choropleth gradient
</ResponseField>

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

<ResponseField name="max" type="number">
  Upper bound for the color scale. Values above this clamp to the last color in the palette. 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 color\_palette with 3 or more colors.
</ResponseField>

<ResponseField name="show_unmatched" type="boolean" default="true">
  Whether to show areas that do not have matching data
</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="name_property" type="string">
  GeoJSON property to use for area name in tooltip (defaults to "NAME")
</ResponseField>

<ResponseField name="value_fmt" type="string" default="num">
  Format for 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)