Release Notes - Map SDK



Released Apr 24, 2024

This release signifies our effort to bring you an experience with a closer integration of various Foursquare products and capabilities, setting up a path for our users to be able to utilize cloud-based geospatial functionality and have more control and security over access and management of individual and organization resources.

See the Migration Guide for more details on how to upgrade.

Breaking changes:

  • Renamed libraries:
  • A new, non-optional parameter (apiKey) is required when creating a new map (see Authentication to learn more about it).
  • Dropped support for Python 3.7 (this affects only Python users). This version of Python officially reached its end-of-life in June 2023 (see Status of Python versions for more information).

New additions:

Additional changes and bug fixes:

  • Improved: Typescript types for layers, annotations, filters and datasets have been adjusted
  • Improved: error messages are more uniform and should provide slightly better information
  • Bug fix: (for JS) map.addToDOM() was fixed, making it easier to mount and unmount, or relocate, the map within DOM
  • Bug fix: the loading spinner has been fixed to be contained within the boundaries of its respective map container
  • Change (internal): a switch to use React 18 has been made - this should provide an improved performance overall
  • Change (internal): bump to using Pydantic v2 for better validation errors and reliability (this change also laid out some of the groundwork for additional API changes that we will be rolling out soon to provide a more ergonomic and idiomatic experience for Python users)


Released Nov 1st, 2023


Released Nov 1st, 2023

  • Bug fix: providing additional Typescript files.


Released Oct 31st, 2023

  • Added addLayerFromConfig, providing safer handling of layer configurations.
  • Improvement: rendering maps with Shadow DOM API, providing much better mutual isolation of styles between Map SDK and the rest of the page; also helping resolve multiple visual bugs.


Released Sep 28th, 2023

  • Added view mode control. Switch the map between 2D, 3D, and Globe view modes.
  • Added support for loading published Studio maps. Called via the constructor, i.e.: createMap(initialState: {publishedMapId: '[UUID]'}).
  • Added the ability to enable/disable drag rotate via setView.
  • Bug fix: Text labels not parsed in layer configurations.


Released Sep 20th, 2023

  • Bug fix: issue encoding characters in HTML.
  • Bug fix: custom base maps failed to load.


Released Sep 14th, 2023


Released Aug 18th, 2023

  • Bug fix: custom base map display issues in the Python Map SDK


Released Aug 2nd, 2023

  • Added columnMode to the LayerConfig type.
  • Bug fix: animation config breaks when multiple trip layers are added.
  • Bug fix: not all layers appear when added individually.
  • Bug fix: updating trip layer sometimes is not reflected properly.


Released June 16th, 2023

  • Bug fix: HTML maps not rendering after function calls.


Released May 17th, 2023

  • Bug fixes and performance improvements


Released May 4, 2023


Release Date: Apr 25, 2023

  • replaceDataset now validates the new dataset for any missing or mismatched columns.
  • The raster layer now supports categorical mapping of color values to raster image pixels.


Release Date: Mar 8, 2023


Release Date: Nov 1, 2022

  • Bug fix: Databricks HTML rendering issues have been resolved.


  • Minor changes related to Foursquare Studio rebranding.


Release Date: Oct 25, 2022


Release Date: Oct 14, 2022


  • Bug fix: Jupyter-related cell synchronization.


Release Date: Sept 27, 2022

  • (On-Prem) Added mapboxAccessToken property to MapCreationProps.basemaps
    • Default map styles will be replaced by custom map styles.
    • On-prem users must specify a custom map style. If left unspecified, only the No Basemap will be available for basemap selection.
  • (On-Prem) Added mapName property to MapCreationProps.uiConfig
    • Defaults mapName = "Studio"


Release Date: Sept 15, 2022



  • Added the uiConfig parameter to MapCreationProps, allowing customization of the leftmost Studio panel. Currently a Pro feature available exclusively on the On-Prem SDK.


  • Fixed an issue when trying to display a map in multiple cells


The initial release of Map SDK v1 presents an improved structure and a variety of new features for both Python and Javascript. In addition to the new functions listed below, existing arguments now accept custom types, providing a more consistent and stable development environment.

Find a full list of functionality in the API overview, then go to any function's page to learn more details about its purpose, accepted arguments, and return properties.

New Dataset Functions
API FunctionDescription
addTileDataset()Adds a new tiled dataset to the map.
getDatasetById()Retrieves a dataset by its identifier.
getDatasetWithData()Retrieves a dataset record with its data for a given dataset.
getDatasets()Gets all datasets available on the map.
replaceDataset()Replaces a given dataset with a new one.
updateDataset()Updates an existing dataset with given values.
New Filter Functions
API FunctionDescription
addFilter()Adds a filter to the map.
getFilterById()Retrieves a filter by its identifier.
getFilters()Gets all the filters currently applied to the map.
removeFilter()Removes a filter from the map.
updateFilter()Updates an existing filter with given values.
updateTimeline()Updates a time range filter timeline with given values.
New Layer Functions
API FunctionDescription
getLayerById()Retrieves a layer by its identifier.
getLayerTimeline()Gets the current layer timeline configuration.
updateLayer()Updates an existing layer with given values.
updateLayerTimeline()Updates the current layer timeline configuration.
New Map Functions
API FunctionDescription
addToDOM()Adds a map into a container element provided as an argument. (Normally called in constructor.)
createMap()Create a new map instance.
getMapConfig()Gets the configuration representing the current map state.
getMapControlVisibility()Gets the map control visibility settings.
getMapStyles()Gets the currently available map styles.
getSplitMode()Gets the split mode of the map.
getView()Gets the current view state of the map.
getViewLimits()Gets the current view limits of the map.
setView()Sets the view state of the map.
setViewLimits()Sets the view limits of the map.


  • Fix to support centerMap in HTMLUnfoldedMap


  • addDataset now has a centerMap boolean parameter that will center the map to a newly added dataset. Defaults to true.


  • setViewState can be used to set a minZoom, maxZoom, and maxBounds.


Starting from this release the versions of JavaScript and Python Map SDK are synced

  • setTheme now allows the user to customize the theme by providing options like the background color of the UI.
  • The Map SDK now allows the user to set the map Split Mode between dual, swipe, or single mode with setSplitMode function. Optionally, passing the layer ids will set layer visibility per split view.


  • Python: Fix default window size in Visual Studio Code.


  • Python: Support for Google Colab notebooks.
  • Python: JupyterLab file opener for GeoJSON and CSV files.
  • Python: Fix a bug where some messages were not correctly received from JavaScript.


  • Python: Add map_config and filters arguments to be used in the HTMLUnfoldedMap constructor.


  • Python: Add get_map_config and set_map_config methods to the UnfoldedMap class.


  • Python: Fix bug where incorrect version of Studio Studio was loaded.


  • Python: Add provisional support for using AWS Location Services basemaps in the Map SDK via _basemap_style and _identity_pool_id arguments to UnfoldedMap.


  • Python: Add support for Databricks notebooks via HTMLUnfoldedMap.
  • JavaScript: Add getMapConfig and setMapConfig methods to the UnfoldedMap class.


Release date: Aug 3, 2021

  • Added onGeometrySelection event handler.


Release date: Jul 8, 2021

  • Added onHover event handler.
  • Added onClick event handler.


Release date: Jun 23, 2021

  • Fixed an issue with addLayer function


Release date: Jun 8, 2021

This release brings support for "local" maps, class based API, new map methods and improved event handling support.

  • JavaScript: UnfoldedMap is now a JavaScript class with methods. This further aligns the JavaScript and Python APIs.
  • UnfoldedMap - "local" maps that are not saved to the Studio cloud can now be created.
  • UnfoldedMap - width and height can now be set to CSS strings providing more control of the resizing of the map.
  • Added addDataset function
  • Added addLayer function
  • Added removeLayer function
  • Added setFilter function
  • Added setMapEventHandlers function
  • Added onFilter event handler.

JavaScript Upgrade Guide

JavaScript only:

  • To create a new map using Unfolded's Map SDK, use the new UnfoldedMap(...) constructor instead of the now deprecated createMap function.
  • Other Map SDK functions are now methods on UnfoldedMap object (created by the new UnfoldedMap(...) constructor). The map object argument should not be passed to the corresponding methods.
  • You now longer need to set appendToDocument in the [new UnfoldedMap(...) constructor unless you want to set it to false.
  • Map now automatically takes full width and height based on the size of the parent container so there is no need to listen on the resize event of the parent container. Values for width and height can also be set to CSS strings providing more control of the resizing of the map.
  • (BREAKING CHANGE) Property appendToDocument that is set in new UnfoldedMap(...) / createMap(...) is now true by default.


  • Added setTimelineConfig function that consolidates timeline settings in a single API.
  • Deprecated setTimelineAnimationSpeed, setTimelineInterval, toggleTimelineVisibility, and toggleTimelineAnimation. You should use setTimelineConfig instead.
  • Added setLayerTimelineConfig function that allows us to use layer timeline features available in certain types of layers.
  • Added getLayerTimelineInfo function that returns information about the layer timeline.


  • Added setTimelineAnimationSpeed function
  • Added getTimelineInfo function
  • Added onTimelineIntervalChange callback function
  • Added isVisible property with the layers returned in getLayers function
  • Bug fixes and performance improvements

0.1.0 - Initial version