# LayersController

***

The Layers controller allows you to get information about the layers on the map, and make changes to their visibility.

Layers can be organised into groups, and their groups can also have their visibility toggled.

## Extended by

* [`FeltController`](https://developers.felt.com/js-sdk-api-reference/main/feltcontroller)

## Methods

### getLayer()

> **getLayer**(`id`: `string`): `Promise`<`null` | [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

Get a single layer from the map by its id.

#### Parameters

| Parameter | Type     | Description                          |
| --------- | -------- | ------------------------------------ |
| `id`      | `string` | The id of the layer you want to get. |

#### Returns

`Promise`<`null` | [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

The requested layer.

#### Example

```typescript
const layer = await felt.getLayer("layer-1");
```

***

### getLayers()

> **getLayers**(`constraint`?: [`GetLayersConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getlayersconstraint)): `Promise`<(`null` | [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer))\[]>

Gets layers from the map, according to the constraints supplied. If no constraints are supplied, all layers will be returned.

#### Parameters

| Parameter     | Type                                                                                                 | Description                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `constraint`? | [`GetLayersConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getlayersconstraint) | The constraints to apply to the layers returned from the map. |

#### Returns

`Promise`<(`null` | [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer))\[]>

All layers on the map.

#### Remarks

The layers in the map, ordered by the order specified in Felt. This is not necessarily the order that they are drawn in, as Felt draws points above lines and lines above polygons, for instance.

#### Example

```typescript
const layers = await felt.getLayers();
```

***

### setLayerVisibility()

> **setLayerVisibility**(`visibility`: [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest)): `Promise`<`void`>

Hide or show layers with the given ids.

#### Parameters

| Parameter    | Type                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| `visibility` | [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest) |

#### Returns

`Promise`<`void`>

#### Example

```typescript
felt.setLayerVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
```

***

### setLayerStyle()

> **setLayerStyle**(`params`: { `id`: `string`; `style`: `object`; }): `Promise`<`void`>

Set the style for a layer using FSL, the Felt Style Language.

Changes are only for this session, and not persisted. This is useful to make temporary changes to a layer's style, such as to highlight a particular layer or feature.

See the [FSL documentation](https://developers.felt.com/felt-style-language) for details on how to read and write styles.

If the style you set is invalid, you will receive an error explaining the problem in the rejected promise value.

#### Parameters

| Parameter      | Type                                   | Description                               |
| -------------- | -------------------------------------- | ----------------------------------------- |
| `params`       | { `id`: `string`; `style`: `object`; } | -                                         |
| `params.id`    | `string`                               | The id of the layer to set the style for. |
| `params.style` | `object`                               | The style to set for the layer.           |

#### Returns

`Promise`<`void`>

#### Example

```typescript
// first get the current style
const oldStyle = (await felt.getLayer("layer-1")).style;

await felt.setLayerStyle({ id: "layer-1", style: {
  ...oldStyle,
  paint: {
    ...oldStyle.paint,
    color: "red",
  },
} });
```

***

### setLayerLegendVisibility()

> **setLayerLegendVisibility**(`params`: [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest)): `Promise`<`void`>

Hide or show layers with the given ids from the legend.

#### Parameters

| Parameter | Type                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `params`  | [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest) |

#### Returns

`Promise`<`void`>

#### Example

```typescript
felt.setLayerLegendVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
```

***

### createLayersFromGeoJson()

> **createLayersFromGeoJson**(`params`: [`CreateLayersFromGeoJsonParams`](https://developers.felt.com/js-sdk-api-reference/layers/createlayersfromgeojsonparams)): `Promise`<`null` | { `layerGroup`: [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup); `layers`: [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)\[]; }>

Adds layers to the map from file or URL sources.

#### Parameters

| Parameter | Type                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------ |
| `params`  | [`CreateLayersFromGeoJsonParams`](https://developers.felt.com/js-sdk-api-reference/layers/createlayersfromgeojsonparams) |

#### Returns

`Promise`<`null` | { `layerGroup`: [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup); `layers`: [`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)\[]; }>

The layer groups that were created.

#### Remarks

This allows you to add temporary layers to the map that don't depend on any processing by Felt. This is useful for viewing data from external sources or remote files.

#### Example

```typescript
const layerFromFile = await felt.createLayersFromGeoJson({
  source: {
    type: "geoJsonFile",
    file: someFile,
  },
  name: "Parcels",
});

const layerFromUrl = await felt.createLayersFromGeoJson({
  source: {
    type: "geoJsonUrl",
    url: "https://example.com/parcels.geojson",
  },
  name: "Parcels",
```

***

### updateLayer()

> **updateLayer**(`params`: [`UpdateLayerParams`](https://developers.felt.com/js-sdk-api-reference/layers/updatelayerparams)): `Promise`<[`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

Update a layer by passing a subset of the layer's properties.

Note that not all properties can be updated, so check the [UpdateLayerParams](https://developers.felt.com/js-sdk-api-reference/layers/updatelayerparams) type to see which properties can be updated.

#### Parameters

| Parameter | Type                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------ |
| `params`  | [`UpdateLayerParams`](https://developers.felt.com/js-sdk-api-reference/layers/updatelayerparams) |

#### Returns

`Promise`<[`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

#### Example

```typescript
await felt.updateLayer({
  id: "layer-1",
  name: "My Layer",
  caption: "A description of the layer",
});
```

***

### deleteLayer()

> **deleteLayer**(`id`: `string`): `Promise`<`void`>

Delete a layer from the map by its id.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `id`      | `string` |

#### Returns

`Promise`<`void`>

#### Remarks

This only works for layers created via the SDK `createLayersFromGeoJson` method, not layers added via the Felt UI.

#### Example

```typescript
await felt.deleteLayer("layer-1");
```

***

### duplicateLayer()

> **duplicateLayer**(`id`: `string`): `Promise`<[`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

Duplicate a layer from the map by its id.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `id`      | `string` |

#### Returns

`Promise`<[`Layer`](https://developers.felt.com/js-sdk-api-reference/layers/layer)>

The duplicated layer.

#### Remarks

This will create an ephemeral copy of the layer, just for the duration of the session. The duplicated layer will not be persisted to the map.

#### Example

```typescript
const duplicatedLayer = await felt.duplicateLayer("layer-1");
```

***

### getLayerGroup()

> **getLayerGroup**(`id`: `string`): `Promise`<`null` | [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup)>

Get a layer group from the map by its id.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `id`      | `string` |

#### Returns

`Promise`<`null` | [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup)>

The requested layer group.

#### Example

```typescript
const layerGroup = await felt.getLayerGroup("layer-group-1");
```

***

### getLayerGroups()

> **getLayerGroups**(`constraint`?: [`GetLayerGroupsConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getlayergroupsconstraint)): `Promise`<(`null` | [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup))\[]>

Gets layer groups from the map, according to the constraints supplied. If no constraints are supplied, all layer groups will be returned in rendering order.

#### Parameters

| Parameter     | Type                                                                                                           | Description                                                         |
| ------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `constraint`? | [`GetLayerGroupsConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getlayergroupsconstraint) | The constraints to apply to the layer groups returned from the map. |

#### Returns

`Promise`<(`null` | [`LayerGroup`](https://developers.felt.com/js-sdk-api-reference/layers/layergroup))\[]>

The requested layer groups.

#### Example

```typescript
const layerGroups = await felt.getLayerGroups({ ids: ["layer-group-1", "layer-group-2"] });
```

***

### setLayerGroupVisibility()

> **setLayerGroupVisibility**(`visibility`: [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest)): `Promise`<`void`>

Hide or show layer groups with the given ids.

#### Parameters

| Parameter    | Type                                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| `visibility` | [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest) |

#### Returns

`Promise`<`void`>

#### Example

```typescript
felt.setLayerGroupVisibility({ show: ["layer-group-1", "layer-group-2"], hide: ["layer-group-3"] });
```

***

### setLayerGroupLegendVisibility()

> **setLayerGroupLegendVisibility**(`params`: [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest)): `Promise`<`void`>

Hide or show layer groups with the given ids from the legend.

#### Parameters

| Parameter | Type                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `params`  | [`SetVisibilityRequest`](https://developers.felt.com/js-sdk-api-reference/shared/setvisibilityrequest) |

#### Returns

`Promise`<`void`>

#### Example

```typescript
felt.setLayerGroupLegendVisibility({ show: ["layer-1", "layer-2"], hide: ["layer-3"] });
```

***

### getLegendItem()

> **getLegendItem**(`id`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)): `Promise`<`null` | [`LegendItem`](https://developers.felt.com/js-sdk-api-reference/layers/legenditem)>

Allows you to get the state of a single legend item.

#### Parameters

| Parameter | Type                                                                                                   |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `id`      | [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier) |

#### Returns

`Promise`<`null` | [`LegendItem`](https://developers.felt.com/js-sdk-api-reference/layers/legenditem)>

#### Example

```typescript
const legendItem = await felt.getLegendItem({
  id: "legend-item-1",
  layerId: "layer-1",
})
```

***

### getLegendItems()

> **getLegendItems**(`constraint`?: [`LegendItemsConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemsconstraint)): `Promise`<(`null` | [`LegendItem`](https://developers.felt.com/js-sdk-api-reference/layers/legenditem))\[]>

Allows you to obtain the state of several legend items, by passing in constraints describing which legend items you want.

If you do not pass any constraints, you will receive all legend items.

#### Parameters

| Parameter     | Type                                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `constraint`? | [`LegendItemsConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemsconstraint) |

#### Returns

`Promise`<(`null` | [`LegendItem`](https://developers.felt.com/js-sdk-api-reference/layers/legenditem))\[]>

#### Example

```typescript
const legendItems = await felt.getLegendItems({layerId: "layer-1"});
```

***

### setLegendItemVisibility()

> **setLegendItemVisibility**(`visibility`: { `show`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]; `hide`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]; }): `Promise`<`void`>

Hide or show legend items with the given identifiers.

#### Parameters

| Parameter          | Type                                                                                                                                                                                                                                      |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `visibility`       | { `show`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]; `hide`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]; } |
| `visibility.show`? | [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]                                                                                                                                 |
| `visibility.hide`? | [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)\[]                                                                                                                                 |

#### Returns

`Promise`<`void`>

#### Example

```typescript
felt.setLegendItemVisibility({
  show: [{layerId: "layer-group-1", id: "item-1-0"}],
  hide: [{layerId: "layer-group-2", id: "item-2-0"}],
})
```

***

### getLayerFilters()

> **getLayerFilters**(`layerId`: `string`): `Promise`<`null` | [`LayerFilters`](https://developers.felt.com/js-sdk-api-reference/layers/layerfilters)>

Get the filters for a layer.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `layerId` | `string` |

#### Returns

`Promise`<`null` | [`LayerFilters`](https://developers.felt.com/js-sdk-api-reference/layers/layerfilters)>

#### Remarks

The return type gives you the filters split up into the various sources that make up the overall filters for a layer.

#### Example

```typescript
const filters = await felt.getLayerFilters("layer-1");
console.log(filters.combined, filters.style, filters.ephemeral, filters.components);
```

***

### setLayerFilters()

> **setLayerFilters**(`params`: { `layerId`: `string`; `filters`: [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters); `note`: `string`; }): `Promise`<`void`>

Sets the **ephemeral** filters for a layer.

#### Parameters

| Parameter        | Type                                                                                                                                | Description                                                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`         | { `layerId`: `string`; `filters`: [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters); `note`: `string`; } | -                                                                                                                                                                    |
| `params.layerId` | `string`                                                                                                                            | The layer that you want to set the filters for.                                                                                                                      |
| `params.filters` | [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters)                                                        | The filters to set for the layer. This will replace any ephemeral filters that are currently set for the layer.                                                      |
| `params.note`?   | `string`                                                                                                                            | A note to display on the layer legend when this filter is applied. When the note is shown, a reset button will also be shown, allowing the user to clear the filter. |

#### Returns

`Promise`<`void`>

#### Example

```typescript
await felt.setLayerFilters({
  layerId: "layer-1",
  filters: ["AREA", "gt", 30_000],
});
```

***

### getLayerBoundaries()

> **getLayerBoundaries**(`layerId`: `string`): `Promise`<`null` | [`LayerBoundaries`](https://developers.felt.com/js-sdk-api-reference/layers/layerboundaries)>

Get the spatial boundaries that are filtering a layer.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `layerId` | `string` |

#### Returns

`Promise`<`null` | [`LayerBoundaries`](https://developers.felt.com/js-sdk-api-reference/layers/layerboundaries)>

#### Remarks

The return type gives you the boundaries split up into the various sources that make up the overall boundary for a layer.

The combined boundary is the intersection of the other sources of boundaries.

#### Example

```typescript
const boundaries = await felt.getLayerBoundaries("layer-1");

console.log(boundaries?.combined);
console.log(boundaries?.spatialFilters);
console.log(boundaries?.ephemeral);
```

***

### setLayerBoundary()

> **setLayerBoundary**(`params`: { `layerIds`: `string`\[]; `boundary`: `null` | [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter); }): `Promise`<`void`>

Set the [\`ephemeral\`](https://developers.felt.com/js-sdk-api-reference/layerboundaries#ephemeral) boundary for one or more layers.

#### Parameters

| Parameter         | Type                                                                                                                                           | Description                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `params`          | { `layerIds`: `string`\[]; `boundary`: `null` \| [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter); } | -                                                                                              |
| `params.layerIds` | `string`\[]                                                                                                                                    | The ids of the layers to set the boundary for.                                                 |
| `params.boundary` | `null` \| [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter)                                           | The boundary to set for the layer. Passing `null` clears the ephemeral boundary for the layer. |

#### Returns

`Promise`<`void`>

#### Example

```typescript
await felt.setLayerBoundary({
  layerIds: ["layer-1", "layer-2"],
  boundary: { type: "MultiPolygon", coordinates: [[[100, 0], [101, 0], [101, 1], [100, 1], [100, 0]]] }
});
```

***

### getRenderedFeatures()

> **getRenderedFeatures**(`params`?: [`GetRenderedFeaturesConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getrenderedfeaturesconstraint)): `Promise`<[`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)\[]>

Get the features that are currently **rendered** on the map in the viewport.

Note that this is explicitly about the features that are rendered, which isn't necessarily a complete list of all the features in the viewport. This is because of the way features are tiled: at low zoom levels or high feature densities, many features are omitted from what is rendered on the screen.

#### Parameters

| Parameter | Type                                                                                                                     | Description                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `params`? | [`GetRenderedFeaturesConstraint`](https://developers.felt.com/js-sdk-api-reference/layers/getrenderedfeaturesconstraint) | The constraints to apply to the features returned from the map. |

#### Returns

`Promise`<[`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)\[]>

#### Example

```typescript
const features = await felt.getRenderedFeatures();
```

***

### getFeature()

> **getFeature**(`params`: { `id`: `string` | `number`; `layerId`: `string`; }): `Promise`<`null` | [`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)>

Get a feature from the map by its ID and layer ID.

The response is a [LayerFeature](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature) object, which does not include the geometry of the feature.

You may want to use this when you don't need the geometry of a feature, but you know the ID of the feature you need.

#### Parameters

| Parameter        | Type                                                 |
| ---------------- | ---------------------------------------------------- |
| `params`         | { `id`: `string` \| `number`; `layerId`: `string`; } |
| `params.id`      | `string` \| `number`                                 |
| `params.layerId` | `string`                                             |

#### Returns

`Promise`<`null` | [`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)>

#### Example

```typescript
const feature = await felt.getFeature({ layerId: "layer-1", id: 123 });
```

***

### getFeatures()

> **getFeatures**(`params`: { `layerId`: `string`; `filters`: [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters); `sorting`: [`SortConfig`](https://developers.felt.com/js-sdk-api-reference/shared/sortconfig); `boundary`: [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter); `search`: `string`; `pagination`: `null` | `string`; `pageSize`: `number`; `select`: `string`\[]; }): `Promise`<{ `features`: [`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)\[]; `count`: `number`; `previousPage`: `null` | `string`; `nextPage`: `null` | `string`; }>

Get a list of layer features.

#### Parameters

| Parameter            | Type                                                                                                                                                                                                                                                                                                                                                                                                                        | Description                                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`             | { `layerId`: `string`; `filters`: [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters); `sorting`: [`SortConfig`](https://developers.felt.com/js-sdk-api-reference/shared/sortconfig); `boundary`: [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter); `search`: `string`; `pagination`: `null` \| `string`; `pageSize`: `number`; `select`: `string`\[]; } | -                                                                                                                                                                |
| `params.layerId`     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                    | The ID of the layer to get features from.                                                                                                                        |
| `params.filters`?    | [`Filters`](https://developers.felt.com/js-sdk-api-reference/layers/filters)                                                                                                                                                                                                                                                                                                                                                | Filters to be applied. These filters will merge with layer's own filters.                                                                                        |
| `params.sorting`?    | [`SortConfig`](https://developers.felt.com/js-sdk-api-reference/shared/sortconfig)                                                                                                                                                                                                                                                                                                                                          | Attribute to sort by.                                                                                                                                            |
| `params.boundary`?   | [`GeometryFilter`](https://developers.felt.com/js-sdk-api-reference/layers/geometryfilter)                                                                                                                                                                                                                                                                                                                                  | The spatial boundary to be applied.                                                                                                                              |
| `params.search`?     | `string`                                                                                                                                                                                                                                                                                                                                                                                                                    | Search term to search by. Search is case-insensitive and looks for matches across all feature properties.                                                        |
| `params.pagination`? | `null` \| `string`                                                                                                                                                                                                                                                                                                                                                                                                          | Pagination token. It comes from either the `previousPage` or `nextPage` properties of the previous response.                                                     |
| `params.pageSize`?   | `number`                                                                                                                                                                                                                                                                                                                                                                                                                    | The number of features to return per page. Defaults to 20. Note: The larger the page size, the longer this is likely to take to respond.                         |
| `params.select`?     | `string`\[]                                                                                                                                                                                                                                                                                                                                                                                                                 | The attributes to select from the features. If not provided, all attributes will be returned. If you set this to an empty array, no attributes will be returned. |

#### Returns

`Promise`<{ `features`: [`LayerFeature`](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature)\[]; `count`: `number`; `previousPage`: `null` | `string`; `nextPage`: `null` | `string`; }>

The response is an object which contains:

* `features`: list of [LayerFeature](https://developers.felt.com/js-sdk-api-reference/layers/layerfeature) objects, which does not include the geometry of the feature but it does include its bounding box.
* `count`: the total number of features that match the query.
* `previousPage` & `nextPage`: The tokens to pass in the `pagination` param to navigate between pages.

#### Remarks

This list is paginated in sets of 20 features for each page. In order to paginate between pages, the response includes `previousPage` and `nextPage` that are tokens that should be sent in the `pagination` params for requesting sibling pages.

Text search is case-insensitive and looks for matches across all feature properties.

#### Example

```typescript
const page1Response = await felt.getFeatures({
  layerId: "layer-1",
  search: "abc123",
  pagination: undefined,
});

// Note that the search term here matches the one for the first page.
if (page1Response.nextPage) {
  const page2Response = await felt.getFeatures({
    layerId: "layer-1",
    search: "abc123",
    pagination: page1Response.nextPage,
  });
}
```

***

### getGeoJsonFeature()

> **getGeoJsonFeature**(`params`: { `id`: `string` | `number`; `layerId`: `string`; }): `Promise`<`null` | [`GeoJsonFeature`](https://developers.felt.com/js-sdk-api-reference/shared/geojsonfeature)>

Get a feature in GeoJSON format from the map by its ID and layer ID.

The response is a GeoJSON Feature object with the complete geometry of the feature. Note that for some *very* large geometries, the response may take a long time to return, and may return a very large object.

#### Parameters

| Parameter        | Type                                                 |
| ---------------- | ---------------------------------------------------- |
| `params`         | { `id`: `string` \| `number`; `layerId`: `string`; } |
| `params.id`      | `string` \| `number`                                 |
| `params.layerId` | `string`                                             |

#### Returns

`Promise`<`null` | [`GeoJsonFeature`](https://developers.felt.com/js-sdk-api-reference/shared/geojsonfeature)>

#### Example

```typescript
const feature = await felt.getGeoJsonFeature({ layerId: "layer-1", id: 123 });
```

***

### getCategoryData()

> **getCategoryData**(`params`: [`GetLayerCategoriesParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercategoriesparams)): `Promise`<[`GetLayerCategoriesGroup`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercategoriesgroup)\[]>

Gets values from a layer grouped by a given attribute.

#### Parameters

| Parameter | Type                                                                                                           |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| `params`  | [`GetLayerCategoriesParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercategoriesparams) |

#### Returns

`Promise`<[`GetLayerCategoriesGroup`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercategoriesgroup)\[]>

#### Remarks

Groups features in your layer by unique values in the specified attribute and calculates a value for each group. By default, this value is the count of features in each group.

You can apply filters in two ways:

1. At the top level (using `boundary` and `filters`), which affects both what categories are included and how values are calculated
2. In the `values` configuration, which only affects the values but keeps all categories

This two-level filtering is particularly useful when you want to compare subsets of data while maintaining consistent categories. For example, you might want to show the distribution of all building types in a city, but only count buildings built after 2000 in each category.

#### Example

```typescript
// Basic grouping: Count of buildings by type
const buildingsByType = await felt.getCategoryData({
  layerId: "buildings",
  attribute: "type"
});

// Filtered grouping: Only count buildings in downtown
const downtownBuildingsByType = await felt.getCategoryData({
  layerId: "buildings",
  attribute: "type",
  boundary: [-122.43, 47.60, -122.33, 47.62]  // downtown boundary
});

// Advanced: Show all building types, but only sum floor area of recent buildings
const recentBuildingAreaByType = await felt.getCategoryData({
  layerId: "buildings",
  attribute: "type",
  values: {
    filters: ["year_built", "gte", 2000],
    aggregation: {
      method: "sum",
      attribute: "floor_area"
    }
  }
});

// Compare residential density across neighborhoods while only counting recent buildings
const newBuildingDensityByNeighborhood = await felt.getCategoryData({
  layerId: "buildings",
  attribute: "neighborhood",
  values: {
    filters: ["year_built", "gte", 2000],
    aggregation: {
      method: "avg",
      attribute: "units_per_acre"
    }
  }
});
```

***

### getHistogramData()

> **getHistogramData**(`params`: [`GetLayerHistogramParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerhistogramparams)): `Promise`<[`GetLayerHistogramBin`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerhistogrambin)\[]>

Gets a histogram of values from a layer for a given attribute.

#### Parameters

| Parameter | Type                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| `params`  | [`GetLayerHistogramParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerhistogramparams) |

#### Returns

`Promise`<[`GetLayerHistogramBin`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerhistogrambin)\[]>

#### Remarks

Creates bins (ranges) for numeric data and counts how many features fall into each bin, or returns aggregated values for each bin.

You can control how the bins are created using the `steps` parameter, choosing from several methods like equal intervals, quantiles, or natural breaks (Jenks), or passing in the step values directly if you know how you want to bin the data.

Like getCategoryData, you can apply filters in two ways:

1. At the top level (using `boundary` and `filters`), which affects both how the bins are calculated and what features are counted in each bin
2. In the `values` configuration, which only affects what gets counted but keeps the bin ranges the same

This is particularly useful when you want to compare distributions while keeping consistent bin ranges. For example, you might want to compare the distribution of building heights in different years while using the same height ranges.

#### Example

```typescript
// Basic histogram: Building heights in 5 natural break bins
const buildingHeights = await felt.getHistogramData({
  layerId: "buildings",
  attribute: "height",
  steps: { type: "jenks", count: 5 }
});

// Compare old vs new buildings using the same height ranges
const oldBuildingHeights = await felt.getHistogramData({
  layerId: "buildings",
  attribute: "height",
  steps: [0, 20, 50, 100, 200, 500],
  values: {
    filters: ["year_built", "lt", 1950]
  }
});

const newBuildingHeights = await felt.getHistogramData({
  layerId: "buildings",
  attribute: "height",
  steps: [0, 20, 50, 100, 200, 500],  // Same ranges as above
  values: {
    filters: ["year_built", "gte", 1950]
  }
});
```

***

### getAggregates()

> **getAggregates**<`T`>(`params`: [`GetLayerCalculationParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercalculationparams)<`T`>): `Promise`<`Record`<`T`, `null` | `number`>>

Calculates a single aggregate value for a layer based on the provided configuration.

#### Type Parameters

| Type Parameter                                                                    |
| --------------------------------------------------------------------------------- |
| `T` *extends* `"min"` \| `"max"` \| `"avg"` \| `"sum"` \| `"median"` \| `"count"` |

#### Parameters

| Parameter | Type                                                                                                                  |
| --------- | --------------------------------------------------------------------------------------------------------------------- |
| `params`  | [`GetLayerCalculationParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayercalculationparams)<`T`> |

#### Returns

`Promise`<`Record`<`T`, `null` | `number`>>

#### Remarks

Performs statistical calculations on your data, like counting features or computing averages, sums, etc. You can focus your calculation on specific areas or subsets of your data using boundaries and filters.

When you request an aggregation other than count, you must specify an attribute to aggregate on.

#### Example

```typescript
// Count all residential buildings
const residentialCount = await felt.getAggregates({
  layerId: "buildings",
  filters: ["type", "eq", "residential"],
  aggregation: {
    methods: ["count"],
  }
});

// Calculate average home value in a specific neighborhood
const avgHomeValue = await felt.getAggregates({
  layerId: "buildings",
  boundary: [-122.43, 47.60, -122.33, 47.62],  // neighborhood boundary
  aggregation: {
    methods: ["avg"],
    attribute: "assessed_value"
  }
});

// Find the maximum building height for buildings built after 2000
const maxNewBuildingHeight = await felt.getAggregates({
  layerId: "buildings",
  filters: ["year_built", "gte", 2000],
  aggregation: {
    methods: ["max"],
    attribute: "height"
  }
});
```

***

### getPrecomputedAggregates()

> **getPrecomputedAggregates**(`params`: [`GetLayerPrecomputedCalculationParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerprecomputedcalculationparams)): `Promise`<{ `avg`: `null` | `number`; `max`: `null` | `number`; `min`: `null` | `number`; `sum`: `null` | `number`; `count`: `null` | `number`; }>

Calculates aggregates for spatial cells of a layer.

#### Parameters

| Parameter | Type                                                                                                                                   |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `params`  | [`GetLayerPrecomputedCalculationParams`](https://developers.felt.com/js-sdk-api-reference/layers/getlayerprecomputedcalculationparams) |

#### Returns

`Promise`<{ `avg`: `null` | `number`; `max`: `null` | `number`; `min`: `null` | `number`; `sum`: `null` | `number`; `count`: `null` | `number`; }>

#### Remarks

Performs statistical calculations on spatial cells of a layer, returning min, max, avg, sum, and count. You can focus your calculation on specific areas or subsets of your data using boundaries and filters. When using the count method, an attribute is not required.

#### Example

```typescript
const aggregates = await felt.getPrecomputedAggregates({
  layerId: "buildings",
  gridConfig: {
    type: "h3",
    resolution: 10,
    method: "avg",
    attribute: "assessed_value"
  },
});
```

***

### getLayerSchema()

> **getLayerSchema**(`layerId`: `string`): `Promise`<[`LayerSchema`](https://developers.felt.com/js-sdk-api-reference/layers/layerschema)>

Get the schema for a layer.

#### Parameters

| Parameter | Type     |
| --------- | -------- |
| `layerId` | `string` |

#### Returns

`Promise`<[`LayerSchema`](https://developers.felt.com/js-sdk-api-reference/layers/layerschema)>

#### Remarks

The schema describes the structure of the data in a layer, including the attributes that are available on the features in the layer.

This can be useful to build generic UIs that need to know the structure of the data in a layer, such as a dropdown to choose an attribute.

#### Example

```typescript
const schema = await felt.getLayerSchema("layer-1");
const attributeIds = schema.attributes.map((attr) => attr.id);
```

## Events

### onLayerChange()

> **onLayerChange**(`args`: { `options`: { `id`: `string`; }; `handler`: (`change`: [`LayerChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layerchangecallbackparams)) => `void`; }): `VoidFunction`

Adds a listener for when a layer changes.

#### Parameters

| Parameter         | Type                                                                                                                                                                                   | Description                                        |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `args`            | { `options`: { `id`: `string`; }; `handler`: (`change`: [`LayerChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layerchangecallbackparams)) => `void`; } | -                                                  |
| `args.options`    | { `id`: `string`; }                                                                                                                                                                    | -                                                  |
| `args.options.id` | `string`                                                                                                                                                                               | The id of the layer to listen for changes to.      |
| `args.handler`    | (`change`: [`LayerChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layerchangecallbackparams)) => `void`                                                 | The handler that is called when the layer changes. |

#### Returns

`VoidFunction`

A function to unsubscribe from the listener

#### Example

```typescript
const unsubscribe = felt.onLayerChange({
  options: { id: "layer-1" },
  handler: ({layer}) => console.log(layer.bounds),
});

// later on...
unsubscribe();
```

***

### onLayerGroupChange()

> **onLayerGroupChange**(`args`: { `options`: { `id`: `string`; }; `handler`: (`change`: [`LayerGroupChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layergroupchangecallbackparams)) => `void`; }): `VoidFunction`

Adds a listener for when a layer group changes.

#### Parameters

| Parameter         | Type                                                                                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `args`            | { `options`: { `id`: `string`; }; `handler`: (`change`: [`LayerGroupChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layergroupchangecallbackparams)) => `void`; } |
| `args.options`    | { `id`: `string`; }                                                                                                                                                                              |
| `args.options.id` | `string`                                                                                                                                                                                         |
| `args.handler`    | (`change`: [`LayerGroupChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/layergroupchangecallbackparams)) => `void`                                                 |

#### Returns

`VoidFunction`

A function to unsubscribe from the listener

#### Example

```typescript
const unsubscribe = felt.onLayerGroupChange({
  options: { id: "layer-group-1" },
  handler: ({layerGroup}) => console.log(layerGroup.id),
});

// later on...
unsubscribe();
```

***

### onLegendItemChange()

> **onLegendItemChange**(`args`: { `options`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier); `handler`: (`change`: [`LegendItemChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemchangecallbackparams)) => `void`; }): `VoidFunction`

Adds a listener for when a legend item changes.

#### Parameters

| Parameter      | Type                                                                                                                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `args`         | { `options`: [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier); `handler`: (`change`: [`LegendItemChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemchangecallbackparams)) => `void`; } |
| `args.options` | [`LegendItemIdentifier`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemidentifier)                                                                                                                                                                              |
| `args.handler` | (`change`: [`LegendItemChangeCallbackParams`](https://developers.felt.com/js-sdk-api-reference/layers/legenditemchangecallbackparams)) => `void`                                                                                                                                    |

#### Returns

`VoidFunction`

A function to unsubscribe from the listener

#### Example

```typescript
const unsubscribe = felt.onLegendItemChange({
  options: { layerId: "layer-1", id: "item-1-0" },
  handler: ({legendItem}) => console.log(legendItem.visible),
});

// later on...
unsubscribe();
```

***

### onLayerFiltersChange()

> **onLayerFiltersChange**(`params`: { `options`: { `layerId`: `string`; }; `handler`: (`change`: [`LayerFilters`](https://developers.felt.com/js-sdk-api-reference/layers/layerfilters)) => `void`; }): `VoidFunction`

Adds a listener for when a layer's filters change.

#### Parameters

| Parameter                | Type                                                                                                                                                              |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`                 | { `options`: { `layerId`: `string`; }; `handler`: (`change`: [`LayerFilters`](https://developers.felt.com/js-sdk-api-reference/layers/layerfilters)) => `void`; } |
| `params.options`         | { `layerId`: `string`; }                                                                                                                                          |
| `params.options.layerId` | `string`                                                                                                                                                          |
| `params.handler`         | (`change`: [`LayerFilters`](https://developers.felt.com/js-sdk-api-reference/layers/layerfilters)) => `void`                                                      |

#### Returns

`VoidFunction`

A function to unsubscribe from the listener

#### Remarks

This event fires whenever any type of filter changes on the layer, including ephemeral filters set via the SDK, style-based filters, or filters set through the Felt UI via Components.

#### Example

```typescript
const unsubscribe = felt.onLayerFiltersChange({
  options: { layerId: "layer-1" },
  handler: ({combined, ephemeral, style, components}) => {
    console.log("Layer filters updated:", {
      combined,  // All filters combined
      ephemeral, // Filters set via SDK
      style,     // Filters from layer style
      components // Filters from UI components
    });
  },
});

// later on...
unsubscribe();
```

***

### onLayerBoundariesChange()

> **onLayerBoundariesChange**(`params`: { `options`: { `layerId`: `string`; }; `handler`: (`boundaries`: `null` | [`LayerBoundaries`](https://developers.felt.com/js-sdk-api-reference/layers/layerboundaries)) => `void`; }): `VoidFunction`

Adds a listener for when a layer's spatial boundaries change.

#### Parameters

| Parameter                | Type                                                                                                                                                                                  | Description                                            |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `params`                 | { `options`: { `layerId`: `string`; }; `handler`: (`boundaries`: `null` \| [`LayerBoundaries`](https://developers.felt.com/js-sdk-api-reference/layers/layerboundaries)) => `void`; } | -                                                      |
| `params.options`         | { `layerId`: `string`; }                                                                                                                                                              | -                                                      |
| `params.options.layerId` | `string`                                                                                                                                                                              | The id of the layer to listen for boundary changes on. |
| `params.handler`         | (`boundaries`: `null` \| [`LayerBoundaries`](https://developers.felt.com/js-sdk-api-reference/layers/layerboundaries)) => `void`                                                      | A function that is called when the boundaries change.  |

#### Returns

`VoidFunction`

A function to unsubscribe from the listener

#### Remarks

This event fires whenever any type of spatial boundary changes on the layer, including ephemeral boundaries set via the SDK or boundaries set through the Felt UI via Spatial filter components.

#### Example

```typescript
const unsubscribe = felt.onLayerBoundariesChange({
  options: { layerId: "layer-1" },
  handler: ({combined, ephemeral, spatialFilters}) => {
    console.log("Layer boundaries updated:", {
      combined,  // All boundaries combined
      ephemeral, // Boundaries set via SDK
      spatialFilters // Boundaries set via UI
    });
  },
});

// later on...
unsubscribe();
```


---

# 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://developers.felt.com/js-sdk-api-reference/layers/layerscontroller.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.