FSL examples

Getting a map's details

Deleting a map

Moving a map

Note: looking for Element-related documentation? They are now called Annotations.

Aggregation popups

Refreshing a layer with a file

1. Request a refresh via the Felt API

2. Upload your file(s) to Amazon S3

Refreshing a layer with a URL

You can get the current selection state using getSelection(). This returns an array of EntityNode objects, each representing a selected entity. The selection can include various types of entities at the same time, such as annotations and features:

Remove current selections using clearSelection():

To stay in sync with selection changes, use the onSelectionChange() method:

1. Clean up listeners: Always store and call the unsubscribe function when you no longer need to listen for selection changes:

1. Handle empty selection: Remember that the selection array might be empty if nothing is selected:

By following these patterns, you can build robust interactions based on what users select in your Felt map.

Selecting features

Reading selection

Clearing selection

Reacting to selection changes

Best practices

For map management beyond creation — reading details, deleting, moving between projects — see Navigating maps and workspaces.

Creating a new map is as simple as making a POST request to the maps endpoint.

You should see a response like this (trimmed for brevity):

Notice the "id" property. Every map has a unique ID, which is also part of the map's URL. Let's take note of it for future API calls.

Also part of the response is a "url" property, which is the URL to your newly-created map. Feel free to open it! For now, it should just show a blank map.

This example uploads from a URL; for file uploads and monitoring processing, see Uploading files and URLs.

Now that we've created a new map, let's add some data to it. We'll need the map_id included in the previous call's response.

Felt supports many kinds of file and URL imports. In this case, we'll import all the recent earthquakes from the USGS' live GeoJSON feed:

Like maps, layers also have unique identifiers. Let's take note of this one (the layer_id field in the response) so we can style it in the next call.

You can see the uploaded result in your map:

For reading a layer's current style and more styling patterns, see Styling layers.

Layers can be styled at upload time or afterwards. Let's change the style of our newly-created earthquakes layer so that points are bigger and in green color:

Go to your map to see how your new layer looks:

For refreshing file-based layers and the full refresh flow, see Refreshing live data layers.

Similar to a URL upload, refreshing an existing URL layer is just a matter of making a single POST request:

Now go to your map and see if any new earthquakes have occurred!

• Authentication — token behavior, rotation, and security.

• Errors and rate limits — what failures look like and how to handle them.

• Listening to updates using webhooks — react to map changes without polling.

• API Reference — every endpoint, generated from the OpenAPI spec.

Endpoints

Create an API token

Install our Python library (optional)

Example: Creating a new map

Example: Uploading a layer from a URL

Example: Styling a layer

Example: Refreshing a live data layer

Next steps

Embed Felt maps in your own applications and control them with the SDK. Here are some examples built with React and hosted on CodeSandbox:

This interactive application leverages the Tool API to enable users to draw custom geometries that retrieve filtered GeoJSON data from an ESRI FeatureService. The application creates a dynamically styled GeoJSON layer to visualize solar potential data, helping users identify optimal locations for solar installations. View the app and code here.

Create powerful business intelligence tools by combining Felt's layer statistics with popular charting libraries. This example demonstrates how to build interactive visualizations that leverage layer filters. View the app and code here.

Enhance map usability with a custom legend that extracts and uses FSL styling information to generate SVG icons. The code demonstrates how to build a nested folder structure with visibility toggles using layer filters, providing a pattern for organizing complex data layers. View the app and code here.

Build comprehensive multi-view dashboards by embedding multiple Felt maps on a single page. This example demonstrates how to create synchronized map views that communicate with each other, enabling users to simultaneously view different geographic contexts or zoom levels of the same data. View the app and code here.

Create engaging interactive experiences with customizable map lenses that reveal different data layers or styling as users explore. This technique allows for compelling before/after comparisons or the ability to highlight specific data attributes within a defined area. View the app and code here.

Provides a pattern for integrating third-party geospatial APIs with Felt maps. This example demonstrates how to make API requests based on annotation geometry and map interactions, process the returned data, and visualize isochrones as dynamic layers. View the app and code here.

Extensions

Commuter patterns

Neighborhood comparison

Animated data

Story map

Embedded maps

Rooftop solar potential

Sales dashboard

Custom legend with nested folders

Inset maps

Lens map

Isochrones

2. Upload your file(s) to Amazon S3

Monitoring progress

You can inspect these different filter sources using getLayerFilters:

Use setLayerFilters to apply ephemeral filters to a layer:

This replaces any ephemeral filters currently set on the layer. You can also pass an optional note — a message shown on the layer legend while the filter is applied, along with a reset button that lets the user clear it:

The following operators are available:

• Comparison: lt (less than), gt (greater than), le (less than or equal), ge (greater than or equal), eq (equal), ne (not equal)

• Text: cn (contains), nc (does not contain)

• Boolean: and, or

• Lookup: in (contained in list), ni (not contained in list)

• Null checks: is / isnt (match against null)

See the filters block for more details on filter operators.

You can combine multiple conditions using boolean operators:

Here's a common use case where we filter a layer to show only features that match a property of a selected feature:

1. Clear filters: Set filters to null to remove them entirely:

1. Check existing filters: Remember that your ephemeral filters combine with existing style and component filters:

1. Type safety: Use TypeScript to ensure your filter expressions are valid:

Understanding filter sources

Setting filters

Filter operators

Compound filters

Practical example: Filtering by selected feature

Best practices

Every style needs a version and a type. Here is a complete, minimal style that draws a point layer in green with a visible stroke:

Paste this into Actions > Edit style language on any point layer and the points turn green immediately. From here, styling is incremental: change "type" to "categorical" or "numeric" to drive color or size from your data, add steps or categories to config, and swap literal colors for @palette shortcuts.

Learn how to define and configure the code blocks that compose the Felt Style Language

Learn about visualization types, including simple, categorical, numeric (color by & size by), heatmaps, H3, and raster (imagery, numeric, categorical, and hillshade).

Shared building blocks referenced throughout the language: smart "auto" colors and named palettes, the icon catalog, and the classification methods used to turn numbers into classes.

Vary paint and label properties with the map's zoom level using interpolators.

Details on how to customize legends on a per-layer basis.

Definitions for errors raised when validating the Felt Style Language.

A compact gallery with one worked example per visualization type.

Where you use FSL

Your first style

Anatomy of a style

Explore the language

Style definition blocks

Types of visualizations

Colors, icons & classification

Zoom-based styling

Legends

Errors

Examples

For continuous (non-stepped) color-by and heatmap legends keyed by index, "0" labels the lowest value and the highest index labels the highest value. Continuous size legends are the historical exception: their indices run inverted, with "0" labeling the maximum, "1" the midpoint, and "2" the minimum.

The Biodiversity Hotspots layer in Felt has a simple visualization with a legend defined as follows:

The Plant Hardiness Zones layer in Felt has a categorical visualization with a legend defined as follows:

The visual display of numeric legends varies based on the style method (stepped or continuous) and the geometry type (point, line, polygon).

The displayName can be modified in the legend block similar to simple and categorical style types.

Heatmap legends are defined as follows:

Notice that the displayName mapping goes from 0 (left value) to 1 (right value)

The legend block

Simple legend

Categorical legend

Numeric legends

Stepped

Continuous

Heatmap legends

All shortcut methods except continuous require a count. Raster algebra visualizations support only continuous and equal-intervals.

There are two ways to define steps.

Shortcut (recommended when you don't know the data's distribution). Name a method and a class count and let Felt compute the break points from the data:

For a smooth gradient, use the continuous shortcut:

Explicit break points (when you know the values you want). Provide the break points directly:

• Classed: N break points produce N − 1 classes. An explicit color or size array must therefore have exactly N − 1 entries. (A palette shortcut such as @galaxy is expanded for you.)

• Continuous: provide 2 or more colors and Felt interpolates between them across the full value range. For proportional symbols, give size: [min, max] and sizes scale smoothly between those two values.

See Numeric visualizations for full color and size examples, and Colors & palettes for palette choices.

Methods

Specifying steps

How breaks map to colors and sizes

A successful response returns your user details, confirming the token works:

From here, head to Getting started to create your first map via the API.

Creating a token

How tokens behave

Making an authenticated request

Every webhook has a signing key, shown in the workspace settings UI when you create it. Felt signs each delivery with a felt-signature HTTP header containing the Base64-encoded HMAC-SHA256 of the raw JSON body, computed with that signing key.

Verify the signature before acting on a payload — it proves the request came from Felt and not from a third party who discovered your URL:

Compute the HMAC over the raw request body exactly as received — re-serializing the parsed JSON can change key order or whitespace and produce a different signature.

Two things are needed in order to make use of webhooks:

1. A Felt map which will serve as the basis for the webhook. Updates will be sent whenever something on this map changes.

2. A webhook URL where the updates will be sent in the form of POST requests.

Workspace admins and editors can set up webhooks in the Developers tab of the Workspace Settings page.

Simply click on Create a new webhook, select a map to listen to changes and paste in a webhook URL where the updates will be sent to.

In order to use webhooks effectively, a receiving service must be set up to trigger actions based on the updates sent by the Felt API. Here are some examples of how to set up a webhook using Felt and an external service.

How webhooks work

Verifying webhook signatures

Requirements

Generating a new webhook

Using your new webhook

When iconImage is set, color fills the icon and size scales it (the same size you would use for a circle radius).

A single icon marker, framed in a circle:

To give each category its own icon, make iconImage an array — see the icon-per-category example in Categorical visualizations.

• Shapes: dot, square, diamond, triangle, x, plus, circle-line, circle-slash, circle-triangle, circle-x, circle-plus, star, heart, hexagon, octagon

• Arrows & directions: arrow-up, chevron-up, double-chevron-up, direction-up (combine with iconRotation to point them anywhere)

• Transportation: pedestrian, bicycle, wheelchair, airport, car, bus, train, truck, ferry, sailboat, electric-service

• Activities & places: person, restroom, house, work, letter, hotel, factory, hospital, religious-facility, school, government

• Infrastructure: zap, battery-full, battery-half, battery-low, boom, radar, wind-turbine, solar-panel, antenna, telephone-pole, oil-well

• Nature: tree, flower, leaf, fire, mountain, snowy-mountain, volcano, island, wave, hot-springs, water

• Weather: sun, moon, cloud, partial-sun, rain, lightning, snowflake, wind, snow, fog, sleet

• Signs: warning, parking, info, circle-exclamation

To use an emoji as a marker, write it as "emoji::name:" — note the double colon after emoji and the trailing colon. For example: "emoji::fire:", "emoji::tree:". iconFrame does not apply to emojis. Prefer built-in icons unless an emoji is specifically requested.

Icon paint properties

Examples

Available icons

Emojis

To test your webhook:

1. Navigate to the Felt map that's linked to the webhook

2. Make any change: add a pin, draw with the marker, change the color of a polygon, update sharing permissions...

3. Back in Pipedream, verify that new events appear for the new source. Note that Pipedream wraps the request in its own envelope — the body field shown by Pipedream is the payload Felt sent:

1. You may also configure a script to run using the above input.

In Felt:

1. Navigate to the Developers tab of your workspace settings and click on Create new webhook

2. Paste the function URL from AWS into the Webhook URL text field, select your map in the dropdown and click Create.

Since the function URL uses Auth type: NONE, anyone who discovers the URL can invoke it — make sure your function verifies the felt-signature header before doing any work.

Use the createLayersFromGeoJson method to add GeoJSON layers to your map. This method accepts different source types depending on where your GeoJSON data comes from.

To create a layer from a GeoJSON file at a remote URL:

To create a layer from a GeoJSON file on the user's device:

To create a layer from GeoJSON data that you've generated or processed in your application. This approach is useful when you need to dynamically generate GeoJSON data based on user interactions or other app states:

When creating GeoJSON layers, you can specify different styles for each geometry type that might be found in your data. The SDK will create separate layers for each geometry type:

Each style should be a valid FSL (Felt Style Language) style. If you don't specify styles, Felt will apply default styles based on the geometry type.

To remove a GeoJSON layer:

Note that this only works for layers created via the SDK's createLayersFromGeoJson method, not for layers added through the Felt UI.

For GeoJSON layers created from URLs, you can set automatic refreshing:

At Creation Time: By setting the refreshInterval parameter when creating the layer. The refreshInterval parameter is optional and specifies how frequently (in milliseconds) the layer should be automatically refreshed from the URL. Valid values range from 250ms to 5 minutes (300,000ms). If set to null or omitted, the layer won't refresh automatically.

Manual refresh: Replace the source property of any layer you have created, using the updateLayer method to update the source data:

Creating GeoJSON layers

From a URL

From a local file

From GeoJSON data

Styling by geometry type

Deleting layers

Refreshing GeoJSON layers

The style for this map is defined

• with the visualization type: numeric

• numericAttribute: "Renter occupied (%)" and the computed steps using Jenks Natural Breaks over 5 classes

• the sequential @galaxy palette, which Felt expands to one color per class — light colors for low values, dark for high

Continuous Color

The map below shows average accumulated precipitation in the State of California between the years 1900 - 1960 and is colored along a continuous range between the min and max of the precipitation values.

In this case, the numeric style is applied using a continuous method.

• In the config block, numericAttribute: PRECIP uses the {"type": "continuous"} steps shortcut, so values scale across the attribute's full min–max range

• The color property uses the sequential @purpYl palette, whose colors are interpolated to give each precipitation value a unique color

Numeric color also works on raster datasets, using band instead of numericAttribute — see Raster visualizations.

Size numeric values in your point or line data using the size property.

Stepped size

The map below shows earthquakes over the past year sized with 5 manually defined steps.

In this case, the numeric style is applied using a classed method.

• In the config block, the numericAttribute: mag has manually-defined steps for 5 classes

• The size property has an array of five sizes, one for each defined class

Map link: Earthquakes Stepped Size

Continuous size

The map below shows tonnes of corn that have been exported from Ukraine since August 2022 under the UN’s Black Sea Grain Initiative. The symbol size for each country is proportionate to its value in the data.

To do this the min and max steps from the numericAttribute: tonnes are interpolated to be proportionately sized between a min and max point size — size:[5,48]

• Let Felt compute breaks when you don't have the data in front of you: "steps": {"type": "jenks", "count": 5}. Provide explicit breaks ([0, 3, 5, 7, 9]) when you know the values you want. See Classification methods.

• Classed arrays carry one value per class. With N break points you get N − 1 classes, so explicit color/size arrays need N − 1 entries.

• Continuous size is written as [min, max] (e.g. [3, 30]) and scales smoothly; proportional-symbol sizes typically range 3–30 px for points. On lines, size is width in pixels (typically 1–20 px), not a radius.

• Continuous size legends use inverted indices for historical reasons: "0" labels the maximum value, "1" the midpoint, and "2" the minimum (as in the example above). Continuous color legends run the intuitive way: "0" is the minimum. See .

• Icons can vary by value too — set iconImage and let size (or color) carry the numeric variable:

Color

Size

Notes on steps, color, and size

All of these keys are siblings at the top level of the object — none are nested inside another:

The shape of a style definition

format accepts any valid numbro format object — common keys include mantissa (decimal places), thousandSeparated, average (compact notation like 1.2M), output ("percent", "currency"), and prefix/postfix. The object is validated by numbro itself, so anything numbro accepts is valid.

Felt adds one extra key on top of numbro: unit, for displaying measurements. Supported values: meter, kilometer, foot, mile, square_meter, hectare, square_kilometer, square_foot, acre, square_mile, and the adaptive auto-distance and auto-area.