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 embed Felt maps into your own applications and use the SDK to control the embedded map experience.

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

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

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

Users represent the people in your workspace.

With these APIs, you can retrieve user profile information.

The Felt SDK provides several methods for reading data from your map's entities (layers, elements, etc.) and staying in sync with their changes. This guide will show you how to read entity data and react to changes.

Getting entities

The Felt SDK provides both singular and plural versions of getter methods for various entity types. This allows you to retrieve either a single entity or multiple entities of the same type.

For example, for layers:

// Get a single layer
const layer = await felt.getLayer("layer-1");

// Get all layers
const layers = await felt.getLayers();

Using constraints

All of the methods that return multiple entities accept constraint parameters to filter the results:

// Get elements with specific IDs
const elements = await felt.getElements({
  ids: ["element-1", "element-2"]
});

// Get legend items belonging to a layer
const legendItems = await felt.getLegendItems({
  layerIds: ["layer-1"],
});

Reacting to changes

To stay in sync with entities, use the appropriate on[EntityType]Change method. For example, to monitor layer changes:

felt.onLayerChange({
  options: {id: "layer-1"},
  handler: ({layer}) => {
    console.log(layer.visible);
  }
});

Best practices

1. Cleanup: Always store and call the unsubscribe functions when you're done listening for changes so that the listener doesn't continue to run in the background.

2. Error handling: When getting entities, remember that the methods may return null if the entity doesn't exist:

const layer = await felt.getLayer("layer-1");
if (layer) {
  // Layer exists, safe to use
  console.log(layer.visible);
} else {
  // Layer not found
  console.log("Layer not found");
}

1. Batch operations: When you need multiple entities, use the bulk methods (getLayers, getElements, etc.) with constraints rather than making multiple individual calls:

// Better approach
const layers = await felt.getLayers({ ids: ["layer-1", "layer-2"] });

// Less efficient approach
const layer1 = await felt.getLayer("layer-1");
const layer2 = await felt.getLayer("layer-2");

This approach to reading and monitoring entities gives you full control over your map's data and allows you to build interactive applications that stay in sync with the map's state.

Maps are the centerpiece of Felt.

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

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.

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.

Embed tokens enable safely sharing your private maps.

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

Projects help you organize maps and manage team permissions.

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

All calls to the Felt API require authorization using a Bearer token in the request header:

These are tokens associated to your account only, and that you have to manually provide to the application you want to use.

Since these tokens grant access to your account, you must store them securely and treat them as a password to your account.

You can create an API token in the :

Be sure to take note of the token before closing the dialog; you won’t have a second chance to view it.

Once you have your API token, you can authenticate your requests to the Felt API by using it as a bearer token in your Authorization header:

Here's an example showing how to create a new Felt map:

Sources connect your databases to Felt.

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

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:

Using Felt.embed to mount into an existing iframe

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:

Using Felt.connect to connect to an existing embedded Felt map

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 Style Language is a way for advanced users to style data quickly, through simple JSON code. This document is a guide to use as you test data files in Felt. For an exhaustive guide to all supported properties see the Reference Documentation.

Style definition blocks

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

Types of visualizations

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

Legends

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

Errors

Definitions for errors raised when validating the Felt Style Language.

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

  • "ge" – Greater than or equal to

  • "eq" – Equal to

  • "ne" – Not equal to

  • "and" – And, cast to boolean

  • "or" – Or, cast to boolean

  • "cn" – Contains the operand, cast to string

  • "nc" – Does not contain the operand, cast to string

  • "in" – Contained in the operand list

  • "ni" – Not contained in the operand list

  • "is" – Used to match against null values

  • "isnt" – Used to match against null values

• 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]

    • Expansion 1: id is equal (”eq”) to one of more of the elements

    • Input 2: [id, "ni", [element1, …, elementN]

    • Expansion 2: id is not equal (”ne”) to any of the elements

    • Not defined for operators other than "in" and "ni"

  • A nested expression

• 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

The legend block contains information on how the legend will be displayed for this visualization.

Take a look at to see how it works.

These are the fields that each legend block can contain:

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:

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

Working with the viewport

Getting viewport state

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

const viewport = await felt.getViewport();
console.log(viewport.center); // { latitude: number, longitude: number }
console.log(viewport.zoom);   // number

Setting the viewport

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

Moving to a point

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

felt.setViewport({
  center: {
    latitude: 37.7749,
    longitude: -122.4194
  },
  zoom: 12
});

Fitting to bounds

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

felt.fitViewportToBounds({
  bounds: [
    west,   // minimum longitude
    south,  // minimum latitude
    east,   // maximum longitude
    north   // maximum latitude
  ]
});

Responding to viewport changes

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

const unsubscribe = felt.onViewportMove({
  handler: (viewport) => {
    console.log("New center:", viewport.center);
    console.log("New zoom:", viewport.zoom);
  }
});

// Clean up when done
unsubscribe();

Map interactions

Click events

Listen for click events on the map using onPointerClick:

const unsubscribe = felt.onPointerClick({
  handler: (event) => {
    // Location of the click
    console.log("Click location:", event.center);
    
    // Features under the click
    console.log("Clicked features:", event.features);
    
    // The pixel coordinates of the cursor, measured from the top left corner of the map DOM element.
    console.log("Screen coordinates:", event.point);
    
    // Raster values, if applicable
    const {value, categoryName, color} = event.rasterValues;
  }
});

Hover events

Track mouse movement over the map using onPointerMove:

const unsubscribe = felt.onPointerMove({
  handler: (event) => {
    // Current mouse location
    console.log("Mouse location:", event.center);
    
    // Features under the cursor
    console.log("Hovered features:", event.features);
    
    // The pixel coordinates of the cursor, measured from the top left corner of the map DOM element.
    console.log("Screen coordinates:", event.point);

    // Raster values, if applicable
    const {value, categoryName, color} = event.rasterValues;
  }
});

Best practices

1. Cleanup: Always store and call unsubscribe functions when you're done listening for events:

const unsubscribe = felt.onPointerMove({
  handler: (event) => {
    // Handle event...
  }
});

// Later, when you're done:
unsubscribe();

1. Throttling: For pointer move events, consider throttling your handler if you're doing expensive operations:

import { throttle } from "lodash";

felt.onPointerMove({
  handler: throttle((event) => {
    // Handle frequent mouse moves...
  }, 100) // Limit to once every 100ms
});

By using these viewport controls and interaction handlers, you can create rich, interactive experiences with your Felt map.

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.

• Attribute ‘dashArray’ has to be a two-numbers array.

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

• Attribute 'showOther' must be one of above, below.

Categorical visualization not working

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

• 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 here.

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 Enterprise plan. All new accounts automatically include a 7-day trial of Enterprise plan features.

See our examples 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

Extensions

Write code directly within Felt using our Extensions feature. Extensions run directly within the Felt environment, giving you immediate access to all SDK functionality without embedding or connection steps.

When creating an extension, you automatically have access to a FeltController object with no setup required. This controller provides all the methods you need to interact with your Felt map, including getViewport, createElement, setLayerStyle, and many more.

// In a Felt extension, the controller is automatically available
const layers = await felt.getLayers();
const elements = await felt.getElements();

// Listen for map events
felt.onSelectionChange((selection) => {
  console.log('Selection changed:', selection);
});

Embedded Maps

Embed Felt maps in your own applications and control them remotely. This approach requires connecting to a map embed.

Installation

Install the SDK using your preferred package manager:

npm install @feltmaps/js-sdk

Create an HTML page with a container element:

<html>
  <body>
    <div id="container"></div>
  </body>
</html>

Embed a Felt map in your container element and use the SDK to control it:

import { Felt } from "@feltmaps/js-sdk";

const map = await Felt.embed(
  document.querySelector("#container"),
  "FELT_MAP_ID",
);

const layers = await map.getLayers();
const elements = await map.getElements();

For more information on how to control a map, see Controlling maps.

React Integration

If you are building a React application, you can use the Felt SDK React Starter Repo to get started quickly.

You can also read our guide on Integrating with React to learn more about how to use the Felt SDK with React.

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

Embedded maps

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

Rooftop Solar Potential

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.

Sales Dashboard

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.

Custom legend with nested folders

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.

Inset maps

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.

Lens Map

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.

Isochrones

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

The shape of a style definition

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.

{
  "version": "2.1",
  "type": "simple",
  "style": {...}
}

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

Heatmaps visualizations are defined using “type”: “heatmap” and, allow the following properties to be set:

This is an example of a heatmap visualization

defined with the following visualization

{
  "version": "2.3",
  "type": "heatmap",
  "config": {},
  "legend": {"displayName": {"0": "Low", "1": "High"}},
  "paint": {"color": "@purpYlPink", "size": 10, "intensity": 0.2}
}

Heatmaps do not support labels.

Hillshades are used to visualize the valleys and ridges encoded in elevation raster data.

Hillshade visualizations are defined using “type”: “hillshade” and, support the following properties:

The following map is an example of a raster layer using a hillshade visualization

with the following style

{
  "version": "2.3",
  "type": "hillshade",
  "config": {"band": 1},
  "legend": {},
  "paint": {"isSandwiched": false}
}

Felt also supports adding color to hillshades by defining a color property in the style

which is defined by the following style

{
  "config": {"band": 1, "steps": [-154.46435546875, 7987.457987843631]},
  "legend": {},
  "type": "hillshade",
  "version": "2.3",
  "paint": {
    "isSandwiched": false,
    "color": "@feltHeat",
    "source": 315,
    "intensity": 0.76
  }
}

Most of the properties used on the style and label blocks can be defined using interpolators to enable zoom-based styling. Take a look at the full list of properties that can be interpolated in the full specification.

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.

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 :

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:

2. Upload your file(s) to Amazon s3

Monitoring progress

You can check the upload status of a layer by querying it:

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 elements, comments or data layers on a fixed interval, a better alternative is to set up a webhook where Felt will send a notification any time a map is updated. This allows you to build integrations on top, such as sending a Slack message or performing calculations for the newly-drawn area.

Requirements

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.

Generating a new webhook

Workspace admins can set up webhooks in the .

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.

Using your new webhook

In order to use webhooks effectively, a receiving layer 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.

This guide covers common patterns and concepts used throughout the Felt SDK.

By following these patterns consistently throughout the SDK, we aim to make the API predictable and easy to use while maintaining flexibility for future enhancements.

Use of promises

All methods in the Felt SDK are asynchronous and return Promises. This means you'll need to use await or .then() when calling them:

Getting entities

The SDK follows a consistent pattern for getting entities. For each entity type, there are usually two methods:

1. A singular getter for retrieving one entity by ID:

1. A plural getter that accepts constraints for retrieving multiple entities:

1. The plural getters allow you to pass no constraints, in which case they'll return all entities of that type:

Change listeners

Each entity type has a corresponding change listener method following the pattern on{EntityType}Change:

There are also various other setters and getters in the Felt SDK that follow this convention as much as possible. For example, selection:

And layer filters:

Cleanup functions

All change listeners return an unsubscribe function that should be called when you no longer need the listener:

This is particularly important in frameworks like React where you should clean up listeners when components unmount:

Handler and options structure

Change listeners always take a single object parameter containing both options and handler. This structure makes it easier to add new options in the future without breaking existing code:

Entity nodes

When dealing with mixed collections of entities (like in selection events), each entity is wrapped in an EntityNode object that includes type information:

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.

Selecting Features

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

• fitViewport (boolean | { maxZoom: number }, default: true) - Whether to fit the viewport to the feature. Can be true, false, or an object with maxZoom to limit the zoom level used.

Reading selection

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

Clearing Selection

Remove current selections using :

Reacting to selection changes

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

Best practices

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.

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.

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

Understanding filter sources

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

2. Component filters: Set through interactive legend components

3. Ephemeral filters: Set temporarily through the SDK

You can inspect these different filter sources using getLayerFilters:

Setting filters

Use setLayerFilters to apply ephemeral filters to a layer:

Filter operators

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)

See for more details on filter operators.

Compound filters

You can combine multiple conditions using boolean operators:

Practical example: Filtering by selected feature

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

Best practices

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:

The Felt SDK provides methods to control the visibility of various entities like layers, layer groups, element 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:

Layers

Control visibility of layer groups using setLayerVisibility:

Layer groups

Control visibility of layer groups using setLayerGroupVisibility:

Element groups

Similarly, control element group visibility with setElementGroupVisibility:

Legend items

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

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:

Toggling visibility

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

Best practices

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:

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.

Embedding with useFeltEmbed

Getting live data

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 map.getLayers():

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.

Vector example

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

and is defined by the following style:

Raster example

This is an example of a simple visualization using a raster dataset

and is defined by the following style:

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:

This is an example of an H3 visualization

defined with the following style

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="<YOUR_API_TOKEN>"

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps" \
  -d '{"title": "My newly created map"}'

import requests

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

r = requests.post(
  "http://felt.com/api/v2/maps",
  json={"title": "My newly created map"},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
map_id = r.json()["id"]

print(r.json())

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"]

Notice in the response the "id" property. Every map has a unique ID, which is also a 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.

Getting a map's details

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.

curl -L \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}"

r = requests.get(
  f"http://felt.com/api/v2/maps/{map_id}",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import get_map

get_map(map_id)

Deleting a map

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

curl -L \
  -X DELETE \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}"

r = requests.delete(
  f"http://felt.com/api/v2/maps/{map_id}",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok

from felt_python import delete_map

delete_map(map_id)

Moving a map

To move a map to a different folder or project, send a POST request to the map's move URL:

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/move" \
  -d '{"project_id": "${PROJECT_ID}"}'

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/move",
  json={"project_id": project_id},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import move_map

move_map(map_id, project_id)

Understanding layer styles

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

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

{
  "config": {"labelAttribute": ["type"]},
  "legend": {},
  "paint": {
    "color": "blue",
    "opacity": 0.9,
    "size": 30,
    "strokeColor": "auto",
    "strokeWidth": 1
  },
  "type": "simple",
  "version": "2.1"
}

Fetching a layer's current style

A layer's FSL can be retrieved by performing a simple GET request to a layer's endpoint:

# Your API token should look like this:
# FELT_API_TOKEN="felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
FELT_API_TOKEN="<YOUR_API_TOKEN>"
MAP_ID="<YOUR_MAP_ID>"
LAYER_ID="<YOUR_LAYER_ID>"

curl -L \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/layers/${LAYER_ID}"

import requests

# Your API token should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"
map_id = "<YOUR_MAP_ID>"
layer_id = "<YOUR_LAYER_ID>"

r = requests.get(
  f"http://felt.com/api/v2/maps/{map_id}/layers/{layer_id}",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

import os

from felt_python import get_layer_details

# 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>"
layer_id = "<YOUR_LAYER_ID>"

layer_details = get_layer_details(map_id, layer_id)

Updating an existing layer's style

To update a layer's style, we can send a POST request with the new FSL to the same layer's /update_style endpoint.

curl -L \
  -X POST \
  "https://felt.com/api/v2/maps/${MAP_ID}/layers/${LAYER_ID}/update_style" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  --data '{"style": {"paint": {"color": "green", "opacity": 0.9, "size": 30, "strokeColor": "auto", "strokeWidth": 1}, "legend": {}, "type": "simple", "version": "2.1"}}'

new_fsl = {
  "paint": {
    "color": "green",
    "opacity": 0.9,
    "size": 30,
    "strokeColor": "auto",
    "strokeWidth": 1
  },
  "legend": {},
  "type": "simple",
  "version": "2.1"
}

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/layers/{layer_id}/update_style",
  json={"style": new_fsl},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import update_layer_style

new_fsl = {
  "paint": {
    "color": "green",
    "opacity": 0.9,
    "size": 30,
    "strokeColor": "auto",
    "strokeWidth": 1
  },
  "legend": {},
  "type": "simple",
  "version": "2.1"
}

update_layer_style(
    map_id=map_id,
    layer_id=layer_id,
    style=new_fsl,
)

FSL examples

You can find examples of FSL for different visualization types in the Felt Style Language section of these docs:

• Simple visualizations: same color and size for all features (vector) or pixels (raster).

• Categorical visualizations: different color per feature or pixel, based on a categorical attribute

• Numeric visualizations: different color or size per feature or pixel, based on a numeric attribute.

• Heatmaps: a density-based visualization style, for vector point layers.

• Hillshade: a special kind of visualization for raster elevation layers.

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.

Refreshing a layer with a file

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

1. Request a refresh via the Felt API

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

import requests

# Your API token should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"
map_id = "<YOUR_MAP_ID>"
layer_id = "<YOUR_LAYER_ID>"

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/layers/{layer_id}/refresh",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
presigned_upload = r.json()

import os

from felt_python import refresh_file_layer

# 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>"
layer_id = "<YOUR_LAYER_ID>"
new_file_name = "<PATH_TO_NEW_FILE>"

refresh_file_layer(
    map_id=map_id,
    layer_id=layer_id,
    file_name=new_file_name
)

2. Upload your file(s) to Amazon s3

# This code is a continuation of the previous Python code block
# and assumes you already have a "presigned_upload" variable
url = presigned_upload["url"]
presigned_attributes = presigned_upload["presigned_attributes"]
# A 204 response indicates that the upload was successful
with open(YOUR_FILE_WITH_EXTENSION, "rb") as file_obj:
    output = requests.post(
        url,
        # Order is important, file should come at the end
        files={**presigned_attributes, "file": file_obj},
    )

# Nothing! Uploading a file is a single step with the felt-python library

Refreshing a layer with a URL

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

# Your API token and map ID should look like this:
# FELT_API_TOKEN="felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
FELT_API_TOKEN="<YOUR_API_TOKEN>"
MAP_ID="<YOUR_MAP_ID>"
LAYER_ID="<YOUR_LAYER_ID>"

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/layers/${LAYER_ID}/refresh"

import requests

# Your API token and map ID should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"
map_id = "<YOUR_MAP_ID>"
layer_id = "<YOUR_LAYER_ID>"

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/layers/{layer_id}/refresh",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import refresh_url_layer

refresh_url_layer(map_id, layer_id)

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, Elements, Sources, Projects and more.

This feature is available to customers on the Enterprise plan. Reach out to set up a trial.

Endpoints

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

https://felt.com/api/v2

Create an API token

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

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

Learn more about API tokens here:

Install our Python library (optional)

The easiest way to interact with the Felt API is by using our felt-python SDK. You can install it with the following command:

pip install felt-python

Example: 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="<YOUR_API_TOKEN>"

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps" \
  -d '{"title": "My newly created map"}'

import requests

# This looks like:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"

r = requests.post(
  "http://felt.com/api/v2/maps",
  json={"title": "My newly created map"},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
map_id = r.json()["id"]

print(r.json())

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"]

Notice in the response the "id" property. Every map has a unique ID, which is also a 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.

Example: Uploading a layer from a URL

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:

# Store the map ID from the previous call:
# MAP_ID="CjU1CMJPTAGofjOK3ICf1D"
MAP_ID="<YOUR_MAP_ID>"

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/upload" \
  -d '{"import_url":"https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson", "name": "USGS Earthquakes"}'

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/upload",
  json={
    "import_url":"https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_hour.geojson",
    "name": "USGS Earthquakes",
  },
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
layer_id = r.json()["layer_id"]

print(r.json())

from felt_python import upload_url

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. Let's take note of this one (also called "id" in the response) so we can style it in the next call.

You can see the uploaded result in your map:

Example: Styling a layer

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:

# Store the layer ID from the previous call:
# LAYER_ID="CjU1CMJPTAGofjOK3ICf1D"
LAYER_ID="<YOUR_LAYER_ID>"

curl -L \
  -X POST \
  "https://felt.com/api/v2/maps/${MAP_ID}/layers/${LAYER_ID}/update_style" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  --data '{"style": {"paint": {"color": "green", "opacity": 0.9, "size": 30, "strokeColor": "auto", "strokeWidth": 1}, "legend": {}, "type": "simple", "version": "2.1"}}'

new_fsl = {
  "paint": {
    "color": "green",
    "opacity": 0.9,
    "size": 30,
    "strokeColor": "auto",
    "strokeWidth": 1
  },
  "legend": {},
  "type": "simple",
  "version": "2.1"
}

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/layers/{layer_id}/update_style",
  json={"style": new_fsl},
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import update_layer_style

new_fsl = {
  "paint": {
    "color": "green",
    "opacity": 0.9,
    "size": 30,
    "strokeColor": "auto",
    "strokeWidth": 1
  },
  "legend": {},
  "type": "simple",
  "version": "2.1"
}

update_layer_style(
    map_id=map_id,
    layer_id=layer_id,
    style=new_fsl,
)

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

Example: Refreshing a live data layer

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

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/layers/${LAYER_ID}/refresh"

r = requests.post(
  f"https://felt.com/api/v2/maps/{map_id}/layers/{layer_id}/refresh",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import refresh_url_layer

refresh_url_layer(map_id, layer_id)

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

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.

To see how a legend is defined, take a look at the legend block section.

Simple legend

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

"legend": {}

Categorical legend

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

"legend": {
  "displayName": {
    "13": "13: 60 to 70 °F",
    "12": "12: 50 to 60 °F",
    "11": "11: 40 to 50 °F",
    "10": "10: 30 to 40 °F",
    "9": "9: 20 to 30 °F",
    "8": "8: 10 to 20 °F",
    "7": "7: 0 to 10 °F",
    "6": "6: -10 to 0 °F",
    "5": "5: -20 to -10 °F",
    "4": "4: -30 to -20 °F",
    "3": "3: -40 to -30 °F",
    "2": "2: -50 to -40 °F",
    "1": "1: -60 to -50 °F"
  }
}

Numeric legends

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.

Stepped

"legend": {
  "displayName": {
    "0": "5.14 to 19.46",
    "1": "19.46 to 26.43",
    "2": "26.43 to 34.06",
    "3": "34.06 to 45.06",
    "4": "45.06 to 100"
  }
}

Continuous

"legend": {
  "displayName": {
    "0": "2.34M", 
    "1": "714.65K", 
    "2": "33K"
  }
}

Heatmap legends

Heatmap legends are defined as follows:

"legend": {
  "displayName": {
    "0": "Low", 
    "1": "High"
 }
}

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

Interpolators

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

Step

{ "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.

{ "step": ["hsl(50,5%,72%)", [[9, "hsl(10,75%,75%)"]] }
// If zoom level is less than 9, "hsl(50,5%,72%)" will be returned
// If zoom level is equal or higher than 9, "hsl(10,75%,75%)" will be returned

The following image shows the behavior of this definition:

{ "step": [0, [[0, 0], [100, 100]]]} // Blue
{ "step": [0, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "step": [0, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

Linear

{ "linear": Stops[] }: Linearly interpolates between stop values less than or equal and greater than the input value

{
  "linear": [
    [8, 10],
    [14, 15],
    [20, 21]
  ]
}
// If zoom level is less than 8, 10 is returned
// If zoom level is greater or equal than 8 but less than 14, a value linearly interpolated
// between 10 and 15 is returned
// If zoom level is greater or equal than 14 but less than 20, a value linearly interpolated // between 15 and 21 is returned
// If zoom level is greater or equal than 20, 21 is returned

The following image shows the behaviour of this definitions

{ "linear": [[0, 0], [100, 100]]} // Blue
{ "linear": [[0, 0], [50, 50], [100, 100]]} // Red
{ "linear": [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]} // Yellow

{ "linear": [number, number] }: Expands to { "linear": [[minZoom, number], [maxZoom, number] }

{ "linear": [8, 10] }
// If minZoom is defined as 3 and maxZoom is defined as 20:
// If zoom level is less than 3, 8 is returned
// If zoom level is between 3 and 20, a value linearly interpolated between 8 and 10 is
// returned
// If zoom level is greater or equal than 20, 10 is returned

Color linear interpolation is done in the HCL color-space

Exponential

{ "exp": [number, Stops[]] }: Exponentially interpolates between output stop values less than or equal and greater than the input value. The base parameter controls the rate at which output increases where higher values increase the output value towards the end of the range, lower values increase the output value towards the start of the range, and a base 1 interpolates linearly.

The used value is computed as follows : (Math.pow(base, progress) - 1) / (Math.pow(base, difference) - 1)

{
  "exp": [
    0.25,
    [
      [0, 25],
      [10, 100]
    ]
  ]
}
// If zoom level is less than 0, 25 is returned
// If zoom level z is between 0 and 10, an interpolation factor is computed between 0 and 10
// and then it's used to interpolate between 25 and 100
// If zoom level is equal or higher than 10, 100 will be returned

The following images shows the behaviour of this definition

{ "exp": [0.25, [[0, 0], [100, 100]]]} // Blue
{ "exp": [0.25, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [0.25, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

{ "exp": [0.5, [[0, 0], [100, 100]]]} // Blue
{ "exp": [0.5, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [0.5, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

{ "exp": [0.75, [[0, 0], [100, 100]]]} // Blue
{ "exp": [0.75, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [0.75, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

{ "exp": [1, [[0, 0], [100, 100]]]} // Blue
{ "exp": [1, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [1, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

{ "exp": [1.25, [[0, 0], [100, 100]]]} // Blue
{ "exp": [1.25, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [1.25, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

{ "exp": [2, [[0, 0], [100, 100]]]} // Blue
{ "exp": [2, [[0, 0], [50, 50], [100, 100]]]} // Red
{ "exp": [2, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]]} // Yellow

Cubic Bezier

{ "cubicbezier": [number, number, number, number, Stops[]] }: Interpolates using the bezier curve defined by the curve control points.

The following images shows the behaviour of this definition

{ "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [100, 100]]]} // Blue
{ "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [50, 50], [100, 100]]} // Red
{ "cubicbezier": [0.25, 0, 0.75, 1.5, [[0, 0], [25, 25], [50, 50], [75, 75], [100, 100]]} // Yellow

Default values

Categorical visualizations use a categorical attribute and the categories within it to apply styling to discrete categories of the attribute. On raster datasets, it uses a band instead of an attribute.

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.

Vector example

The Global Power Plants layer in Felt is an example of a categorical layer on a vector dataset

and is defined by the following style

{
  "version": "2.3",
  "type": "categorical",
  "config": {
    "categoricalAttribute": "primary_fuel",
    "categories": ["Solar", "Hydro", "Wind", "Gas", "Coal", "Oil", "Nuclear"],
    "showOther": false
  },
  "legend": {"displayName": {}},
  "attributes": {
    "capacity_mw": {"displayName": "Capacity (MW)"},
    "name": {"displayName": "Name"},
    "primary_fuel": {"displayName": "Primary Fuel"}
  },
  "paint": {
    "color": [
      "#E5C550",
      "#7AB6C2",
      "#AB71A4",
      "#CC615C",
      "#AD7B68",
      "#EB9360",
      "#DEA145"
    ],
    "isSandwiched": false,
    "opacity": 1,
    "size": [{"linear": [[3, 1.5], [20, 8]]}]
  }
}

Notice that we are saying that the primary_fuel data attribute will be used to categorize elements and that the possible values of that attribute that we are interested in are "Nuclear", "Oil", "Coal", "Gas", "Wind", "Hydro" and "Solar". Also notice that we are defining either a single value that will apply to all categories (i.e. size) or a value for each category (i.e. color)

Raster example

The Cropscape CDL layer in Felt is an example of a categorical layer on a raster dataset

and is defined by the following style:

{
  "version": "2.3",
  "type": "categorical",
  "config": {
    "categories": [
      254,
      250,
      249,
      248,
      247,
      ...
      4,
      3,
      2,
      1,
      0
    ],
    "showOther": false
  },
  "legend": {
    "displayName": {
      "0": "Background",
      "1": "Corn",
      "2": "Cotton",
      "3": "Rice",
      "4": "Sorghum",
      ...
      "247": "Turnips",
      "248": "Eggplants",
      "249": "Gourds",
      "250": "Cranberries",
      "254": "Dbl Crop Barley/Soybeans"
    }
  },
  "paint": {
    "color": [
      "rgb(38, 113, 0)",
      "rgb(252, 105, 101)",
      "rgb(252, 105, 101)",
      "rgb(252, 105, 101)",
      "rgb(252, 105, 101)",
      ...
      "RGB(255, 158, 15)",
      "RGB(0, 169, 230)",
      "RGB(255, 38, 38)",
      "RGB(255, 212, 0)",
      "rgba(0, 0, 0, 0)"
    ],
    "isSandwiched": false,
    "opacity": 0.93
  }
}

Elements live at the top layer of a map, and are created directly inside the Felt app.

Listing all elements on a map

Elements live at the top layer of a map, and are created directly inside the Felt app.

Elements are returned as a GeoJSON Feature Collection.

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

curl -L \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/elements"

import requests

# Your API token and map ID should look like this:
# api_token = "felt_pat_ABCDEFUDQPAGGNBmX40YNhkCRvvLI3f8/BCwD/g8"
api_token = "<YOUR_API_TOKEN>"
map_id = "<YOUR_MAP_ID>"

r = requests.get(
  f"http://felt.com/api/v2/maps/{map_id}/elements",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

import os

from felt_python import list_elements

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

list_elements(map_id)

Listing all element groups

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

curl -L \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/element_groups"

r = requests.get(
  f"http://felt.com/api/v2/maps/{map_id}/elements",
  headers={"Authorization": f"Bearer {api_token}"}
)
assert r.ok
print(r.json())

from felt_python import list_element_groups

list_element_groups(map_id)

Create or update new elements

Each element is represented by a feature in the POSTed GeoJSON Feature Collection.

For each feature, including an existing element ID (felt:id) will result in the element being updated on the map. If no element ID is provided (or a non-existent one) , a new element will be created.

curl -L \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/elements" \
  -d '{"type":"FeatureCollection","features":[{"type":"Feature","properties":{},"geometry":{"coordinates":[[[15.478752514432728,15.576176978045694],[15.478752514432728,4.005934587045303],[29.892174099255755,4.005934587045303],[29.892174099255755,15.576176978045694],[15.478752514432728,15.576176978045694]]],"type":"Polygon"}}]}'

new_elements = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [
              15.478752514432728,
              15.576176978045694
            ],
            [
              15.478752514432728,
              4.005934587045303
            ],
            [
              29.892174099255755,
              4.005934587045303
            ],
            [
              29.892174099255755,
              15.576176978045694
            ],
            [
              15.478752514432728,
              15.576176978045694
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  ]
}

r = requests.post(
  f"http://felt.com/api/v2/maps/{map_id}/elements",
  headers={"Authorization": f"Bearer {api_token}"},
  json=new_elements
)
assert r.ok
print(r.json())

from felt_python import upsert_elements

new_elements = {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {},
      "geometry": {
        "coordinates": [
          [
            [
              15.478752514432728,
              15.576176978045694
            ],
            [
              15.478752514432728,
              4.005934587045303
            ],
            [
              29.892174099255755,
              4.005934587045303
            ],
            [
              29.892174099255755,
              15.576176978045694
            ],
            [
              15.478752514432728,
              15.576176978045694
            ]
          ]
        ],
        "type": "Polygon"
      }
    }
  ]
}

upsert_elements(map_id, new_elements)

Delete an element

Elements can be deleted by referencing them by ID

curl -L \
  -X DELETE \
  -H "Authorization: Bearer ${FELT_API_TOKEN}" \
  "https://felt.com/api/v2/maps/${MAP_ID}/elements/{ELEMENT_ID}"

element_id = "<YOUR_ELEMENT_ID>"

r = requests.delete(
  f"http://felt.com/api/v2/maps/{map_id}/elements/{element_id}",
  headers={"Authorization": f"Bearer {api_token}"},
)
assert r.ok

from felt_python import delete_element

element_id = "<YOUR_ELEMENT_ID>"

delete_element(map_id, element_id)

The config block contains configuration options for a given visualization.

These are the fields that each config block can contain:

Default Values

Examples

"config": [
	{
    "labelAttribute": ["Wikipedia", "faa"],
		"categoricalAttribute": "faa",
		"categories": ["faa-code-1", "faa-code-2", "faa-code-3"],
		"showOther": true,
		"otherOrder": "above"
	}
]

"config": [
	{
    "labelAttribute": ["Wikipedia", "faa"],
		"numericAttribute": "percentage",
		"steps": [1, 25, 50, 75, 100]
	}
]

"config": {
  "band": 1,
  "method": {"NDVI": {"NIR": 1, "R": 2}},
  "steps": [-0.5, 0.5]
},

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.

Creating GeoJSON layers

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

From a URL

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

const layerResult = await felt.createLayersFromGeoJson({
  source: {
    type: "geoJsonUrl",
    url: "https://example.com/data/neighborhoods.geojson",
    // Optional: Auto-refresh every 30 seconds
    refreshInterval: 30000
  },
  name: "Neighborhoods",
  caption: "Neighborhood boundaries for the city", // Optional
  description: "This layer shows the official neighborhood boundaries" // Optional
});

if (layerResult) {
  console.log("Created layer group:", layerResult.layerGroup);
  console.log("Created layers:", layerResult.layers);
}

From a local file

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

// Assuming you have a File object from a file input
const fileInput = document.getElementById('geojson-upload');
const file = fileInput.files[0];

const layerResult = await felt.createLayersFromGeoJson({
  source: {
    type: "geoJsonFile",
    file: file
  },
  name: "User Uploaded Data"
});

if (layerResult) {
  // Store the layer ID for later reference
  const layerId = layerResult.layers[0].id;
}