Projects help you organize maps and manage team permissions.

With these APIs, you can manage the projects in your workspace.

With these APIs, you can create and edit a layer's components.

Layers enable you to visualize, style and interact with your spatial data.

With these APIs, you can upload data, manage layer styling, publish and refresh live data layers.

With these APIs, you can upload your data to create new layers.

Felt’s Developer Tools

There are a variety of ways to interact with Felt’s modern GIS platform outside of the user interface. They can be grouped into two buckets: tools for programmatically creating and modifying maps, and tools for building custom experiences for map viewers. These tools can be used to solve distinct challenges and also be used in tandem with one another.

Creating and modifying maps

Felt’s REST API allows editors to interact with the Felt platform via code, performing actions such as creating new maps, adding data to maps, styling layers, and more. The REST API can be leveraged from any environment that is capable of sending GET and POST requests.

For Python users, interactions with the REST API are simplified through the felt-python module, which can be installed with pip and used to call the REST API endpoints directly from Python functions.

Creating custom applications

Felt’s user interface allows a large amount of customization, offering the ability to generate complex cartographic designs, adding components to create a dashboard, and much more.

However, sometimes application developers need further control over the experience of viewing and/or interacting with a map. For example, they may want to run custom logic after a user clicks on a feature in a layer, or animate data on the map based on other types of user input elsewhere on the webpage. For these situations and many more, Felt’s JavaScript SDK allows developers to programmatically control maps in two ways: Extensions let you write custom code directly within Felt maps, with access to all SDK functionality. Alternatively, you can Felt maps into your own applications and use the SDK to control the embedded map experience.

All calls to the Felt API authenticate with a personal access token sent as a Bearer token in the request header:

Authorization: Bearer <API Token>

Tokens start with the felt_pat_ prefix. Since a token grants access to your account, store it securely — treat it like a password. Prefer environment variables or a secrets manager over hardcoding tokens in source code.

Creating a token

You can create an API token in the Developers tab of the Workspace Settings page:

Be sure to take note of the token before closing the dialog; you won't have a second chance to view it. Only a hash of your token is stored on Felt's servers.

How tokens behave

• Workspace-scoped. Each token belongs to the workspace it was created in and can only access that workspace's resources. Requests against another workspace's resources fail with 401.

• They act as you. Requests made with your token have your account's permissions in that workspace.

• No expiry. Tokens remain valid until revoked. To rotate a token, create a new one in workspace settings, switch your integration over, and revoke the old one.

• Failed authentication returns 401 with a JSON body explaining the problem — see .

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

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

Maps are the centerpiece of Felt.

With these APIs, you can create, retrieve, update, delete, move, and duplicate maps programmatically.

With these APIs, you can export data to CSV, GeoJSON, and other formats.

Sources connect your databases to Felt.

With these APIs, you can configure data source connections, credentials, and sync settings to create live maps.

Embed tokens enable safely sharing your private maps.

With these APIs, you can generate secure tokens for embedding maps.

With these APIs, you can render a map to a PNG, JPG or PDF image.

Users represent the people in your workspace.

With these APIs, you can retrieve user profile information.

Elements enable you to annotate maps with custom shapes, text, and markers.

With these APIs, you can create, update, and delete map elements.

Comments bring conversations to mapping.

With these APIs, you can export, resolve, and delete map comments and collaboration threads.

Workspaces and API tokens

Workspaces are the place where users in the same organization collaborate and share maps. A user may form part of several workspaces but, at the very least, always forms part of one.

API tokens are created per-workspace. If you wish to interact with several workspaces via the Felt API, you must create a different API token for each one.

Working with maps

Creating a new map

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

# Your API token should look like this:
# FELT_API_TOKEN="felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
FELT_API_TOKEN="

import requests

# Your API token should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"

import os

from felt_python import create_map

# Setting your API token as an env variable can save
# you from repeating it in every function call
os.environ["FELT_API_TOKEN"] = "<YOUR_API_TOKEN>"

response = create_map(
    title="My newly created map",
    lat=40,
    lon=-3,
    public_access="private",
)
map_id = response["id"]

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

{
  "id": "CjU1CMJPTAGofjOK3ICf1D",
  "type": "map",
  "title": "My newly created map",
  "url": "https://felt.com/map/My-newly-created-map-CjU1CMJPTAGofjOK3ICf1D",
  "public_access": "view_only",
  "layers": [],
  "created_at": "2024-05-25T15:51:34"
}

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.

Performing a GET request to a map URL will give you useful information about that map, including title, URL, layers, thumbnail URL, creation and visited timestamps.

To remove a map from your workspace, simply perform a DELETE request to the map's URL:

To move a map to a different folder or project, send a POST request to the map's move URL with either a project_id or a folder_id in the body. You can find project IDs by listing your projects with GET /api/v2/projects:

Uploading a URL

The easiest way of uploading data into a Felt map via the API is to import from a URL. Here's an example importing all the recent earthquakes from the USGS' live GeoJSON feed:

# Your API token and map ID should look like this:
# FELT_API_TOKEN="felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
# MAP_ID="CjU1CMJPTAGofjOK3ICf1D"

import requests

# Your API token should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"

import os

from felt_python import upload_url

# Setting your API token as an env variable can save
# you from repeating it in every function call
os.environ["FELT_API_TOKEN"] = "<YOUR_API_TOKEN>"

map_id = "<YOUR_MAP_ID>"

url_upload = upload_url(
    map_id=map_id,
    layer_url="https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson",
    layer_name="USGS Earthquakes",
)
layer_id = url_upload["layer_id"]

Like maps, layers also have unique identifiers. Make sure to take note of them for subsequent calls, like styling a layer or removing it.

Uploading a file

Files aren't uploaded to the Felt app — instead, they're uploaded directly to Amazon S3. Therefore, creating a layer from a file on your computer is a two-step process:

1. Request an upload via the Felt API

Perform a POST request to receive an S3 presigned URL which you can later upload your files to:

r = requests.post(
    f"https://felt.com/api/v2/maps/{map_id}/upload",
    headers={
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json",
    },
    json={"name": "My new layer"},
)
assert r.ok
layer_id = r.json()["layer_id"]

presigned_upload = r.json()

from felt_python import upload_file

file_name = "<YOUR_FILE_WITH_EXTENSION>" # Example: regions.geojson

upload_file(
  map_id=map_id,
  file_name=file_name,
  layer_name="My new layer",
)

You can check the upload status of a layer by querying it. The response includes two useful fields:

• progress — a number from 0 to 100, the percentage complete. Typed as a float in the API spec, so don't assume an integer.

• status — one of uploading, processing, completed, or failed.

Poll until status is completed (or failed). A layer must reach completed before it can be styled or .

With these APIs, you can publish your layers to your workspace library.

The Felt REST API allows you to programmatically interact with the Felt platform, enabling you to integrate Felt's powerful mapping capabilities into your own workflows and pipelines.

You are able to create and manipulate Maps, Layers, Annotations, Sources, Projects and more.

The REST API is available on select . Reach out to to learn more or set up a trial.

All Felt API endpoints are hosted at the following base URL:

All calls to the Felt API must be authenticated. The easiest way to authenticate your API calls is by creating an API token and providing it as a Bearer token in the request header.

You can create an API token in the :

Learn more about API tokens here:

The easiest way to interact with the Felt API is by using our

The Felt SDK has a number of methods for interacting with maps, depending on how you set up your HTML.

All Felt maps are embedded in iframes, and the SDK can do this for you or can connect to an existing Felt iframe.

Felt map IDs

Felt map IDs are unique identifiers for Felt maps. They are used to embed maps in iframes, and to connect to existing iframes.

To get the ID of a Felt map, click the Map settings button in the main toolbar, and then you can see the Map ID in the Developers section.

Alternatively, you can look at the URL of the map. For example, the map at https://felt.com/map/Map-title-xPV9BqMuYQxmUraVWy9C89BNA has the ID xPV9BqMuYQxmUraVWy9C89BNA.

Throughout the documentation, we'll use the placeholder FELT_MAP_ID to refer to a Felt map ID.

Using Felt.embed to create an iframe

Create an HTML page with a container element:

Embed a Felt map in your container element and use the SDK to control it by calling Felt.embed, passing the container element as the first argument:

Felt.embed also takes a third argument with options controlling the embed's UI, initial viewport, and authentication — see .

In some cases, you may want to add a "template" iframe to your page. This can be useful if you want to style your iframe in a specific way, or if you already have one map embedded and want to mount and control a different map.

In this case, you can call Felt.embed with the iframe element as the first argument:

There may be cases where you already have a Felt map embedded in an iframe, and you want to control it using the SDK. This can be useful if your HTML is server-rendered with the Felt map already embedded.

In this case, you can call Felt.connect with the iframe's window as the first argument:

Note that in this case, you don't need to pass the Felt map ID to Felt.connect, because we are connecting to a map that has already been embedded.

The Felt SDK provides methods to control the visibility of various entities like layers, layer groups, annotation groups, and legend items. These methods are designed to efficiently handle bulk operations.

Understanding visibility requests

All visibility methods use a consistent structure that allows both showing and hiding entities in a single call:

{
  show?: string[],  // IDs of entities to show
  hide?: string[]   // IDs of entities to hide
}

Layers

Control visibility of layers using setLayerVisibility:

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

Layer groups

Control visibility of layer groups using setLayerGroupVisibility:

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

Annotation groups

Similarly, control annotation group visibility with setElementGroupVisibility:

felt.setElementGroupVisibility({
  show: ["points-group"],
  hide: ["lines-group", "polygons-group"]
});

Legend items

Legend items require both a layer ID and an item ID to identify them. Use setLegendItemVisibility:

felt.setLegendItemVisibility({
  show: [
    { layerId: "layer-1", id: "item-1" },
    { layerId: "layer-1", id: "item-2" }
  ],
  hide: [
    { layerId: "layer-1", id: "item-3" }
  ]
});

Common use cases

Focusing on a single layer

To focus on a single layer by hiding all others, first get all layers and then use their IDs:

When implementing a toggle, you can use empty arrays for the operation you don't need:

1. Batch operations: Use a single call with multiple IDs rather than making multiple calls:

1. Omit unused properties: When you only need to show or hide, omit the unused property rather than including it with an empty array:

The attributes block contains information on how attributes will be shown both on the popup and the table. Each attribute definition can contain the following properties:

format accepts any valid — 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

Most of the properties used on the paint and label blocks can be defined using interpolators to enable zoom-based styling — the property tables on those pages mark which ones accept an Interpolator.

We support multiple types of interpolators: Step functions, linear, exponential and cubic bezier to enable your map looking like you want at each zoom level. See the Interpolators page.

An example of a layer changing feature colors depending on the zoom level can be found below

"paint": {
  "color": {"linear": [[14, "red"], [20, "blue"]]}
}

On zoom levels lower than 14, features of this layer will be rendered in red color. On zoom levels higher than 20, features of this layer will be rendered in blue color.

In zooms between 14 and 20, color will be linearly interpolated between red and blue.

Style validation errors surface as a banner in the in-app style editor, and as 422 responses with the message in the error detail when styling via the REST API. The JS SDK rejects the setLayerStyle promise with the validation message.

Unexpected value or type

Problem: One of the values set in the style has an unsupported value or an invalid type.

Solution: Change the value to be valid.

Error messages:

• Attribute 'displayName' on a legend item of type simple must be a string.

• Attribute attribute_name is not a number.

• Attribute attribute_name is not a string.

• Attribute 'lineCap' is not a supported value. Supported values are butt, round, square.

• Attribute 'lineJoin' is not a supported value. Supported values are bevel, round, miter.

• Visualization dashArray has to be an array with even length.

• Attribute 'offset' must be either an array of numbers or a number.

• Attribute 'placement' contains a not supported value. Supported values are N, NE, E, SE, S, SW, W, NW, Center.

• Attribute 'placement' contains a not supported value. Supported values are Above, Center, Below.

• All values in 'labelAttribute' must be a string.

• Visualization 'type' definition must be one of simple, categorical, numeric, heatmap, hillshade, h3.

• Attribute 'showOther' must be one of above, below. (Despite the wording, this message refers to the otherOrder field — showOther itself is a boolean, while otherOrder must be "above" or "below".)

Problem: The style defines a categorical visualization, but the maps are not showing the layer

Error messages:

• Categories required. A categories array must be defined in the config block when defining a categorical visualization. Read more about categorical visualizations .

• Not enough or too many attribute_name values. When defining a categorical visualization, all style and label properties must be an array with either a single value that will apply to all categories or an array with as many values as categories defined in the config block. Read more about categorical visualizations .

The type field chooses how a layer's data is turned into a picture. Pick the type that matches your data and message:

Each page lists the geometry types it applies to, the properties that matter, and worked examples. For the values you'll plug into these styles, see , , and .

, , and (numeric and tinted hillshade) visualizations all turn a range of values into discrete classes (or a smooth gradient) using the steps field in the config block. The classification method decides where the breaks between classes fall.

It's common to have data update on a regular basis, such as every week or every month. Instead of having to re-upload and style the new data, it can be very convenient to simply refresh a layer using a new data source.

Just like , refreshing a layer with a new file is a two-step process:

Perform a POST request to receive an S3 presigned URL which you can later upload your files to:

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

The Felt SDK allows you to control your Felt maps and build powerful, interactive custom applications. You can control many aspects of the Felt UI and map contents, as well as receive notifications of events happening in the map such as clicks, selections, and more.

This feature is available to customers on the . Reach out to .

See our page to explore what you can build with the SDK.

There are two main ways to use the Felt SDK:

1. Extensions

2. Embedded maps

Almost every error returned by the Felt API uses the same JSON envelope: an errors array where each entry has a title, a human-readable detail, usually a stable code, and — where applicable — a source telling you which header, parameter, or body field caused the problem.

Treat code as best-effort rather than guaranteed: a few responses — notably field-validation failures and plan-limit errors — carry only title and detail. Branch on the HTTP status first, and use code

The Felt SDK allows you to filter which features are visible in a layer using expressions that evaluate against feature properties. Filters can come from different sources and are combined to determine what's visible.

Note that filters only work on layers that have been uploaded to and processed by Felt — layers created at runtime with cannot be filtered.

By understanding how filters work and combine, you can create dynamic views of your data that respond to user interactions and application state.

Layer filters can come from multiple sources, which are combined to create the final filter:

1. Style filters: Set by the map creator in the Felt UI

A great way of building data-driven apps using Felt is by triggering a workflow whenever something changes on a map, like someone drawing a polygon around an area of interest or updating the details on a pin.

Instead of polling by listing annotations, comments or data layers on a fixed interval, set up a webhook and Felt will send your endpoint a notification any time a map is updated. This allows you to build integrations on top, such as sending a Slack message or recalculating statistics for a newly-drawn area.

Each webhook is attached to a single map. Whenever the map changes — annotations drawn or edited, layers updated, comments added or resolved — Felt sends a POST request with a JSON body to your webhook URL:

A few things to know about the delivery model:

• Event types. map:update

A layer's style is defined in a JSON-based format called , or FSL for short. Editors can view the current style of a layer inside a Felt map by clicking on Actions > Edit style language in a layer's overflow menu (three dots).

Here is an example of a simple visualization, expressed in FSL:

A layer's FSL can be retrieved by performing a simple GET request to a layer's endpoint — the response's style field contains the current style object:

To update a layer's style, we can send a POST

A style in its most basic form contains a version definition but it can be extended to define how we want geometry and labels to show on the map, how the legend should look like, what information is shown in popups and the formatting used when displaying feature properties.

The table below describes which properties can be used in the style definition.

Heatmaps are used to visualize the density of points on a map.

Heatmaps work on point layers only, and show concentration rather than individual feature values — if you need to read a specific attribute, use a visualization instead. The config block must be empty ({}), and heatmaps support no popups or labels.

Heatmap visualizations are defined using "type": "heatmap" and allow the following properties to be set:

A compact, one-per-type overview. For fuller, captioned examples — line casing, proportional symbols, icon-per-category, H3 aggregation popups, raster algebra — see the individual pages.

The popup block contains information on how the popup is displayed and which attributes to show.

These are the fields that each popup block can contain:

The Felt SDK allows you to add GeoJSON data to your maps from various sources:

• Remote URLs

• Local files

• Programmatically generated GeoJSON data

GeoJSON layers created via the SDK are temporary and session-specific - they're not permanently added to the map and won't be visible to other users.

When creating a GeoJSON layer, you can specify different styles for each geometry type (Point, Line, Polygon) that might be found in the source. Each geometry type will create its own layer. It's important to note that GeoJSON layers added via the SDK have limited capabilities compared to regular Felt layers - they cannot be filtered, nor can statistics be fetched for them.

Use the 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 (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 method to update the source data:

Explore examples of what you can build with the Felt SDK. These examples showcase different approaches to creating interactive map experiences - from extensions that run directly within Felt to embedded maps in custom applications.

Extensions

Extensions run directly within Felt maps, giving you immediate access to all SDK functionality. Here are some examples built using AI assistance:

Commuter patterns

Visualize transportation patterns by drawing lines to destination counties on click. Features travel mode options and filtering capabilities to analyze commuting data across different regions. View the map here.

Neighborhood comparison

Compare neighborhoods side-by-side with automated analysis of land use patterns. This tool helps users understand demographic and geographic differences between areas. View the map here.

Animated data

Bring geographic data to life with animations showing the flow of the Mississippi River Basin from headwaters to the Gulf of Mexico, demonstrating how to create compelling temporal visualizations. View the map here.

Story map

Guide users through agricultural regions with an interactive narrative experience that combines storytelling with geographic exploration. View the map .

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 .

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 .

Enhance map usability with a custom legend that extracts and uses 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 .

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 .

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 .

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 .

Felt.embed() takes an optional third argument that controls how the embedded map looks and behaves:

const felt = await Felt.embed(container, FELT_MAP_ID, {
  uiControls: {
    showLegend: false,
    cooperativeGestures: false,
  },
  initialViewport: {
    center: { latitude: 40.7128, longitude: -74.006 },
    zoom: 10,
  },
});

UI controls

All uiControls options are booleans:

You can change these after the map has loaded with :

initialViewport overrides the map's saved viewport with a center and zoom for this embed:

Public and unlisted maps embed with no extra configuration. To embed a private map for visitors who aren't logged into Felt, generate a short-lived embed token server-side with the REST API and pass it as the token option:

1. Your server calls , using your . The visitor's user_email is a required query parameter, not a body field, and that address should belong to a member of your workspace. The response contains a token valid for 15 minutes.

2. Your page passes that token to Felt.embed:

Never call the embed token endpoint from the browser — that would expose your API token. Generate embed tokens on your server and hand only the short-lived token to the client.

The filters block contains information on how the layer is being filtered before displaying. In order for a feature to be shown on the map it must evaluate the filter expression to true.

Filters are written using a JSON infix notation that looks like one of [identifier, operator, operand], true or false .

• Valid identifiers are either a feature property or a nested expression.

• Valid operators are:

  • "lt" – Less than

  • "gt" – Greater than

  • "le" – Less than or equal to

• Operands are:

  • A numerical value, a string value, a boolean value

  • An array of numerical, string, or boolean values, a shorthand expanded to these patterns:

    • Input 1: [id, "in", [element1, …, elementN]]

• In cases of type mismatch cast the identifier value to the operand’s type

  • Type casting applies element-wise to lists with "in" and "ni" operators

• Case & diacritics: eq, ne, gt, ge, lt, le, cn, and nc compare strings case-insensitively and diacritic-insensitively. ["status", "eq", "active"] matches "Active"

There is no single "between" operator — combine two comparisons:

Check that a value exists and is non-empty:

Three or more conditions must be written as nested pairs, not a flat list:

Adding a legend block to a visualization makes a legend entry appear for this visualization.

Each legend entry is shown with the geometry type and color defined by the dataset and the visualization block.

While simple visualizations will generate a single legend entry, categorical visualizations will generate a legend entry per category.

The legend block

The only field is displayName. For categorical visualizations it maps each category to its label; for numeric/heatmap visualizations it maps the index of each class ("0", "1", …) to its label. Set "displayName": "auto" to let Felt generate the labels for you — from the computed breaks for numeric classes, or from the category names for categorical visualizations ("auto" requires steps or categories to be set in config). An empty legend: {} still produces a legend entry using the dataset's geometry and color.

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)

This guide covers the mental model and the common patterns used throughout the Felt SDK. Understanding these once makes every other page predictable.

Everything you do with the SDK goes through a controller object — named felt in all the examples in these docs. How you get it depends on where your code runs:

• Embeds — your code runs in your page, and the map lives in an iframe. Felt.embed(container, mapId, options) creates the iframe and returns a controller for it. You can also use Felt.connect(iframe.contentWindow) to attach a controller to a Felt iframe you've already placed on the page. See and .

Annotations sit on top of all data layers on a map. They are usually drawn in the Felt app, but can also be created and updated via the API.

Annotations are returned as a .

Returns a list of GeoJSON Feature Collections, one for each annotation group.

Each annotation is represented by a feature in the POST

To work with Felt embeds in React, we have a starter template that you can use as a starting point.

This is available on GitHub in the repository.

In that repo, you will find a feltUtils.ts file that demonstrates some ways to make using the Felt SDK in React easier. The SDK itself is framework-agnostic and ships no React bindings — the hooks below are small wrappers you copy into your own project.

A common use case for building apps on Felt is to be notified when entities are updated. The main example of this is when you want to change the visibility of say a layer, and have your own UI reflect that change.

Rather than keeping track of the visibility of entities yourself, you can use the Felt SDK to listen for changes to the visibility of entities.

Here is an example of how you might do this for layers assuming you already have a reference to a Layer object, e.g. from calling felt.getLayers():

Every listener on the Felt controller follows the same pattern: you pass a handler (and sometimes an options object scoping the listener to a specific entity), and the call returns an unsubscribe function.

Always call the unsubscribe function when your UI unmounts or the listener is no longer needed.

Simple visualizations are those that show each feature in a vector dataset using the same style or the image as it is in raster ones.

Simple visualizations must define "type": "simple" and a single value for each supported style and label properties.

The Airports layer in Felt is an example of a simple visualization using a vector dataset

and is defined by the following style:

Raster layers can also use simple to display imagery as-is — see .

Icon markers (points). Set iconImage to draw points as icons; the icon takes the layer's color

H3 visualization is a way to aggregate point data into a grid of H3 cells.

H3 visualizations are defined using "type": "h3" . They generally share the same properties and behaviors as . Properties of specific relevance to H3 are:

Categorical visualizations use a categorical attribute and the categories within it to apply styling to discrete categories of the attribute. (On raster datasets, categories are raw pixel values instead — see .)

Categorical visualizations are defined using "type": "categorical" and, for every supported style and label property used, either a single value that will apply to all categories or an array of different values for each category.

You can list the categories explicitly, or use a shortcut when you don't know the exact values: {"type": "top", "count": N} keeps the N most common values (vector), and {"type": "all"} covers every unique pixel value (raster). When showOther: true is combined with an explicit categories array, paint/label arrays need

The Felt SDK provides functionality for reading the current selection state and selecting features on the map programmatically. This is useful for building interactive experiences that respond to data analysis or user interactions.

Features are individual data points within layers. You can select features programmatically using the method. Only one feature can be selected at a time - selecting a new feature will replace the current selection.

The method accepts options to control the selection behavior:

• showPopup (boolean, default: true) - Whether to display the feature information popup

The Felt SDK provides methods to control the map's viewport (the visible area of the map) and handle user interactions like clicking and hovering on the viewport.

You can get the current viewport state using getViewport():

There are two main ways to set the viewport: moving to a specific point, or fitting to bounds.

Use setViewport() to move the map to a specific location:

Use fitViewportToBounds() to adjust the viewport to show a specific rectangular area:

To stay in sync with viewport changes, use the onViewportMove method:

Interpolators are functions that use the current zoom level to get you a value. The following interpolators are currently supported:

{ "step": [output0, Stops[]] }: Computes discrete results by evaluating a piecewise-constant function defined by stops on a given input. Returns the output value of the stop with a stop input value just less than the input one. If the input value is less than the input of the first stop, output0 is returned.

Stops are defined as pairs of [zoom, value] where zoom is the minimum zoom level where value is returned and value can be number | string | boolean. Note that stops need to be defined by increasing zoom level.