1 of 51

Home

Overview

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

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.

REST API

Getting started

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.

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.

# 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

A layer must have finished uploading successfully before it can be refreshed

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!

Navigating maps and workspaces

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_details

get_map_details(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)

Uploading files and URLs

Uploading a URL

# 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 \
  -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"}'

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

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

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

Uploading a file is a single function call using the felt-python library.

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="YOUR_FILE_WITH_EXTENSION",
  layer_name="My new layer",
)

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

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

url = presigned_upload["url"]
presigned_attributes = presigned_upload["presigned_attributes"]
# A 204 response indicates that the upload was successful
with open(file_name, "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

Monitoring progress

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

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

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

from felt_python import get_layer_details

get_layer_details(map_id, layer_id)["progress"]

Styling layers

Understanding layer styles

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

Refreshing live data 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.

A layer must have finished uploading successfully before it can be refreshed

Refreshing a layer with a file

Refreshing a file is a single function call using the felt-python library.

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

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

Working with elements

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.

# 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 post_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"
      }
    }
  ]
}

post_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)

Listening to updates using webhooks

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:

A Felt map which will serve as the basis for the webhook. Updates will be sent whenever something on this map changes.
A webhook URL where the updates will be sent in the form of POST requests.

Generating a new webhook

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.

Setting up an example webhook using Pipedream

Create a free Pipedream account
On the left-hand sidebar, navigate to Sources, then click on New source in the top-right corner.
Select HTTP / Webhook, then New Requests (Payload Only), and give your newly-created source a name.
Copy the endpoint URL. It will look like https://XXX.m.pipedream.net
Paste the endpoint URL from Pipedream into the Webhook URL text field, select your map in the dropdown and click Create.

To test your webhook:

Navigate to the Felt map that's linked to the webhook
Make any change: add a pin, draw with the marker, change the color of a polygon, update sharing permissions...
Back in Pipedream, verify that new events appear for the new source. The payload should look like this:

{
  "body": {
    "attributes": {
      "type": "map:update",
      "updated_at": "2024-04-29T12:16:46",
      "map_id": "Jzjr8gMKSrCOxZ1OSMT49CB"
    }
  }
}

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

Setting up an example webhook using an AWS Lambda

Serverless functions like AWS Lambda or Google Cloud Functions are an excellent way of triggering code after a map update by setting them to run after a specific HTTP call.

In the AWS console, navigate to Lambda and click on Create function
Choose a name and runtime and, under Advanced Settings, make sure to check Enable function URL
Set Auth type to NONE and click on Create function
In the next screen, copy the Function URL. It should look like https://{LAMBDA_ID}.lambda-url.{REGION}.on.aws
Continue configuring your Lambda function as usual by editing the code that will run on map updates

In Felt:

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

API Reference

Authentication

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.

API tokens are scoped to a workspace, meaning that you can only work with resources associated to that workspace only.

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:

Maps

Create a new map

Several aspects can be customized when creating a new map, including:

Title
Initial location (latitude, longitude and zoom level)
Sharing permissions (defaults to viewing and commenting for users with the map URL)
An array of URLs to import on map creation

Delete an existing map

Get details of a map

Returns details including title, URL, thumbnail URL, creation and visited timestamps.

Update a map's details

Update the title, description and access permissions of a map.

Move a map

Move a map to a different project or folder. Project IDs and Folder IDs can be found inside map settings.

Layers

Uploading a file or URL

The /upload endpoint can be used for both URL and file uploads:

For URL uploads, simply making a single POST request to the upload endpoint is enough
For file uploads, the response of the initial POST request will include a target URL and some pre-signed attributes, which will be used to upload the new file to Amazon S3.

This endpoint is used to create a layer, and obtain a pre-signed url to upload the layer files to S3.

Uploading the file to Amazon S3

Uploading a file is a single function call using the felt-python library.

Layer files aren’t uploaded directly to the Felt API. Instead, they are uploaded by your client directly to an S3 bucket.

You will receive a single set of URL and pre-signed params to upload the file. Only a single file may be uploaded — if you wish to upload several files at once, consider wrapping them in a zip file.

To upload the file using the pre-signed params, you must perform a multipart upload, and include the file contents in the file field:

# Requires requests library to be installed with: pip install requests
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>"
path_to_file = "<YOUR_FILE_WITH_EXTENSION>" # Example: features.geojson

# Request  a pre-signed URL from Felt
layer_response = 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"},
)
presigned_upload = layer_response.json()
url = presigned_upload["data"]["attributes"]["url"]
presigned_attributes = presigned_upload["data"]["attributes"]["presigned_attributes"]
# A 204 response indicates that the upload was successful
with open(path_to_file, "rb") as file_obj:
    output = requests.post(
        url,
        # Order is important, file should come at the end
        files={**presigned_attributes, "file": file_obj},
    )

from felt_python import upload_file

map_id = "<YOUR_MAP_ID>"
path_to_file = "<YOUR_FILE_WITH_EXTENSION>" # Example: features.geojson

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

Refreshing a layer

Refreshing a file is a single function call using the felt-python library.

After uploading a file or URL, you may want to update the resulting layer with some new data. The process is quite similar to the above:

For URL uploads, simply making a single POST request to the refresh endpoint is enough
For file uploads, the response of the initial POST request will include a URL and some presigned attributes, which will be used to upload the new file to Amazon S3. See Uploading the file to Amazon S3 for more details.

Deleting a layer

Styling layers

Update a layer's style

A layer's style may be updated by providing a new Felt Style Language object. Learn more in the guide:

Managing layers

Get all the layers on a map

Get the details of all the layer on the map that are not within a layer group.

Get a single layer

Get the details of a single layer on the map. These details include:

Name of the layer
Upload status and progress
Other metadata, such as the geometry type, visibility state in the legend, etc

Updating a layer's details

Update a layer's name or move it into or out of a layer group.

To move a layer into a group, set the layer_group_id to the id of the layer group you want to move the layer into. To move a layer out of a group, set the layer_group_id to null.

Layer groups

Get details of a layer group

Delete a layer group

Create or update layer groups

Provide an array of layer group objects to create new groups or update existing ones.

For each layer group object, including an existing ID will result in the group's details (name, subtitle and legend order) being updated. If no layer group ID is provided (or a non-existent one is provided), a new layer group will be created.

Layer library

Listing layers

List all layers in your workspace's Library

Publishing a layer

Publish a layer to your workspace's library

Publishing a layer group

Publish a layer group to your workspace's library

Downloading layers

Get a link to export a layer as a GeoPackage (vector layers) or GeoTIFF (raster layers)

Create Custom Export Request

Create an export request of a layer as a GeoPackage, GeoJSON, or CSV. Optionally include filters with the layer. Export requests are asynchronous. A successful response will return a poll_endpoint to check the status of the export.

Poll Custom Export Request

Check the status of an Custom Export. If successful, the response will include a download_url

Duplicating layers

Duplicate an array of layers or layer groups to a map

Elements

List all elements on a map

Returns a GeoJSON FeatureCollection containing all the elements in a map that are not in an element group

List all elements in a group

Returns a GeoJSON FeatureCollection containing all the elements in a single group

List all element groups on a map

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

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

The maximum payload size for any POST to the Felt API is 1MB. Additionally, complex element geometry may be automatically simplified. If you require large, complex geometries, consider uploading your data as a Data Layer.

Create or update new element groups

For each Element Group, including an existing Element Group id will result in the Element Group being updated. If no id is provided, a new Element Group will be created.

You may assign Elements to an Element Group by setting the felt:parentId property of an Element to the ID of an Element Group.

Delete an element

Deletes the element with the ID specified in the path.

Users

Get own details

Returns information about the user issuing the request

Comments

Export comments from a map

Returns an export of the map comments.

The export can be generated in JSON or CSV format, you can specify the format with the format query parameter, which can be either json or csv. It defaults to json.

Resolve a comment

Resolve an individual comment based on it's ID.

Delete a comment

Embed Tokens

Generate an Embed Token

Creates a short-lived (15 minutes) token for authenticating a visitor to view a private embedded map view without being logged into Felt.

Usage

Generate a token by making a call to this API from your server
Securely pass the token to your frontend client
Include the token as a query parameter on the Embed URL in an iframe

<iframe src="https://felt.com/embed/map/{mapId}?token={token}"></iframe>

Enabling Layer Export

You can allow EmbedToken based page views to export layer data.

Include a user_email query parameter when creating the EmbedToken
Turn on "Viewer permissions: Export data" in Map settings

Sources

List Sources

Lists Sources that you have access to. To see the datasets in an individual Source, fetch it from the Show Source endpoint.

Show Source

Fetches a single Source and all the datasets it contains.

Create a Source

Triggers the creation of a new Source. Each connection type has it's own set of required parameters, depending on what kind of Source it is. These are provided in the connection field.

Connecting the Source and inspecting it's datasets will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for sync_status: completed.

Sync a Source

Triggers Felt to reconnect to your Source and re-inspect all the datasets it contains. Syncing will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for sync_status: completed.

Update a Source

Updates details of a Source. Connecting the Source and inspecting it's datasets will happen asynchronously after the API response is returned. To determine when the inspection process has completed, poll the Show Source endpoint and check for sync_status: completed.

Delete a Source

Deletes a Source.

Any layers created from the Source will remain after it is deleted, but they will no longer be refreshed.

Projects

List projects

List projects that you have access to.

Show a project

Returns details of a project including name, visibility, id and a list of references to the maps in the project.

Create a project

Create a new project with the provided name and visibility.

Update a project

Update a project's name or visibility.

Delete a project

Delete a project and all of it's contents.

Caution: Deleting a project deletes all of the folders and maps inside!

JS SDK

Getting started

The Felt SDK allows you to embed, connect to and ultimately control Felt map embeds, allowing you to build powerful, interactive custom applications around Felt.

You are able to control many aspects of the Felt UI and map contents, as well as being notified of events happening in the map such as clicks, selections, etc.

Installation

Assuming you are using a modern JavaScript environment, install the SDK using your preferred package manager:

Create an HTML page with a container element:

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

React

General concepts

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:

const layer = await felt.getLayer("layer-1");
felt.getElements().then(elements => {
  console.log(elements);
});

Getting entities

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

A singular getter for retrieving one entity by ID:

const layer = await felt.getLayer("layer-1");
const element = await felt.getElement("element-1");

A plural getter that accepts constraints for retrieving multiple entities:

const layers = await felt.getLayers({ ids: ["layer-1", "layer-2"] });
const legendItems = await felt.getLegendItems({ layerIds: ["layer-1", "layer-2"] });

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

const layers = await felt.getLayers();
const elements = await felt.getLegendItems();

Change listeners

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

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

This is true of selection, which acts as a kind-of entity in its own right:

const selection = await felt.getSelection();
const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    console.log("Selection updated:", selection);
  }
});

Cleanup functions

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

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

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

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

useEffect(() => {
  const unsubscribe = felt.onViewportMove({
    handler: (viewport) => {
      console.log("Viewport changed:", viewport);
    }
  });
  
  // Clean up when the component unmounts
  return () => unsubscribe();
}, []);

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:

// Current API
felt.onElementChange({
  options: { id: "element-1" },
  handler: ({ element }) => { /* ... */ }
});

// If we need to add new options later, no breaking changes:
felt.onElementChange({
  options: { 
    id: "element-1",
    newOption: "value" // Can add new options without breaking existing code
  },
  handler: ({ element }) => { /* ... */ }
});

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:

felt.onSelectionChange({
  handler: ({ selection }) => {
    selection.forEach(node => {
      console.log(node.type);    // e.g., "element", "layer", "feature", ...
      console.log(node.entity);  // The actual entity object
      
      if (node.type === "element") {
        // TypeScript knows this is an Element
        console.log(node.entity.attributes);
      }
    });
  }
});

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

Working with selection

The Felt SDK provides methods to read and react to selection changes in your map. Selection refers to the currently highlighted entities (elements, features, etc.) that the user has clicked on or selected through other means.

Reading selection

You can get the current selection state using getSelection():

const selection = await felt.getSelection();

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

Reacting to selection changes

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

const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    // selection is an array of EntityNode objects
    console.log("Selected entities:", selection);
    
    // Check what's selected
    selection.forEach(node => {
      console.log("Entity type:", node.type);
      console.log("Entity ID:", node.entity.id);
    });
  }
});

// Don't forget to clean up when you're done
unsubscribe();

Best practices

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

const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    // Handle selection...
  }
});

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

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

const unsubscribe = felt.onSelectionChange({
  handler: ({ selection }) => {
    if (selection.length === 0) {
      console.log("Nothing is selected");
      return;
    }
    // Handle selection...
  }
});

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

Reading entities

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:

Using constraints

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

Reacting to changes

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

Best practices

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.
Error handling: When getting entities, remember that the methods may return null if the entity doesn't exist:

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

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.

Map interactions and viewport

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():

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:

Fitting to bounds

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

Responding to viewport changes

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

Map interactions

Click events

Listen for click events on the map using onPointerClick:

Hover events

Track mouse movement over the map using onPointerMove:

Best practices

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

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

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

Hiding and showing

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:

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

Layers

Control visibility of layer groups 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"]
});

Element groups

Similarly, control element 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:

const layers = await felt.getLayers();
const targetLayerId = "important-layer";

felt.setLayerVisibility({
  show: [targetLayerId],
  hide: layers
    .map(layer => layer?.id)
    .filter(id => id && id !== targetLayerId)
});

Toggling visibility

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

function toggleLayer(layerId: string, visible: boolean) {
  felt.setLayerVisibility({
    show: visible ? [layerId] : [],
    hide: visible ? [] : [layerId]
  });
}

Best practices

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

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

// Less efficient approach
felt.setLayerVisibility({ show: ["layer-1"] });
felt.setLayerVisibility({ show: ["layer-2"] });
felt.setLayerVisibility({ hide: ["layer-3"] });
felt.setLayerVisibility({ hide: ["layer-4"] });

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

// Do this
felt.setLayerVisibility({
  show: ["layer-1"]
});

Layer filters

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:

Style filters: Set by the map creator in the Felt UI
Component filters: Set through interactive legend components
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)

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

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

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

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

Sample application

This is a sample application showing how to use the Felt SDK to build an app with the following features:

listing the map's layers
toggling layer visibility
moving the viewport to center it on predefined city locations

The commented code in its entirety is shown below.

Integrating with React

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

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`

function MyComponent() {
  // get the felt controller (or null if it's not loaded yet) and a ref to the map container
  // into which we can embed the map
  const { felt, mapRef } = useFeltEmbed("wPV9BqMuYQxmUraVWy9C89BNA", {
    uiControls: {
      cooperativeGestures: false,
      fullScreenButton: false,
      showLegend: false,
    },
  });

  return (
    <div>
      {/* the map container */}
      <div ref={mapRef} />

      {/* a component that uses the Felt controller */}
      <MyFeltApp felt={felt} />
    </div>
  );
}

useFeltEmbed implementation

import {
  Felt,
  FeltController,
  FeltEmbedOptions,
  Layer,
  LayerGroup,
} from "@feltmaps/js-sdk";
import React from "react";

export function useFeltEmbed(mapId: string, embedOptions: FeltEmbedOptions) {
  const [felt, setFelt] = React.useState<FeltController | null>(null);
  const hasLoadedRef = React.useRef(false);
  const mapRef = React.useRef<HTMLDivElement>(null);

  React.useEffect(() => {
    async function loadFelt() {
      if (hasLoadedRef.current) return;
      if (!mapRef.current) return;

      hasLoadedRef.current = true;
      const felt = await Felt.embed(mapRef.current, mapId, embedOptions);
      setFelt(felt);
    }

    loadFelt();
  }, []);

  return {
    felt,
    mapRef,
  };
}

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():

export function useLiveLayer(felt: FeltController, initialLayer: Layer) {
  // start with the layer we were given
  const [currentLayer, setLayer] = React.useState<Layer | null>(initialLayer);

  // listen for changes to the layer and update our state accordingly
  React.useEffect(() => {
    return felt.onLayerChange({
      options: { id: initialLayer.id },
      handler: ({ layer }) => setLayer(layer),
    });
  }, [initialLayer.id]);

  // return the live layer
  return currentLayer;
}

Felt Style Language

Getting started

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.

Style definition blocks

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

The paint block

The paint block defines how feature geometries and raster pixels are rendered.

Properties common to all visualization types.

Simple visualizations

The following properties are available for the simple type of visualization

Categorical and numeric visualizations

Label block reference

These are the properties available to define label rendering. Anchors can be lines or points, polygons are not supported.

Default values

The legend block

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

These are the fields that each legend block can contain:

Example of a categorical legend

"legend": {
  "displayName": {
    "category-1": "Category 1",
    "category-2": "Category 2"
  }
}

Example of a numerical legend

"legend": {
  "displayName": {
    "0": "-0.5", 
    "1": "0.5"
  }
}

The popup block

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:

Field name

Description

titleAttribute

Optional. The attribute that will be used to title the popup if available

imageAttribute

Optional. The attribute that will be used to populate the popup image if available

popupLayout

Optional. One of either “table” or “list”. The way the popup will show its contents. Defaults to "table"

keyAttributes

Optional. A list of attributes to show in the popup following the order defined here. If it’s not defined, only attributes with a value will show in the popup. If it’s defined, all attributes here will show even if the selected feature doesn’t include them.

Example of a popup block

"popup": {
  "keyAttributes": [
    "osm_id",
    "barriers",
    "highway",
    "ref",
    "is_in",
    "place",
    "man_made",
    "other_tags"
  ],
  "titleAttribute": "barriers",
  "popupLayout": "list"
}

The attributes block

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 filters block

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

Types of visualizations

Simple visualizations

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:

Categorical visualizations

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

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)