Jupyter Notebooks

The Studio platform is available in Jupyter Notebooks as a set of Python APIs.

Jupyter (formerly known as IPython Notebook) is a web-based, interactive Python environment widely used for data science, machine learning, statistics, and many other fields. Along with kernels for Python, Scala, and R, Jupyter can display media, math equations, rich text, and markdown. Combining this extensive support with popular libraries such as pandas, Jupyter Notebooks provide an optimal environment for capturing a computation process, executing code in blocks and communicating the results.

Notebooks and Studio

Using notebooks with Studio offer numerous capabilities to geospatial analysts and data scientists:

Studio MapsEmbed and control Studio maps in notebooks via the Map SDK for Python.
Cloud Assets and AnalyticsManage geospatial datasets and maps and invoke Studio analytics services such as Hex Tiles from notebook environments via the Studio Data SDK for Python.
Data Science OptimizedStudio APIs integrate with major Python data science packages and workflows.
Cloud Notebook SupportStudio supports commercial cloud notebooks providers (e.g. DataBricks).

Supported Notebook Environments

Studio offers support for several major notebook environments. However, as Notebook environments offer different feature sets with unique limitations, Studio's notebook support is not platform-agnostic. For more information, see interactive widgets.

Depending on your environment, several notebook extensions may be required. Please refer to additional installation instructions in the Studio documentation page corresponding to your notebook environment.

Python Packages


Two Studio Python packages provide full access to the Studio Platform:

Python PackageDescription
foursquare.map_sdkThe Map SDK for Python enables display of interactive Studio maps inside Jupyter notebooks. It also provides Python methods to control embedded maps, e.g. to change map settings, add new data layers, and much more.
unfolded.data_sdkThe Studio Data SDK for Python enables Python notebooks to access Studio platform cloud services and assets. Notebooks can create, upload, and download datasets and access all other functions in the Data SDK.

To install Studio packages using pip:

$ pip install unfolded.map-sdk unfolded.data-sdk

Interactive Widgets

The most notable variable across notebook environments is the support of interactive widgets. Support for these widgets varies across platforms, with some environments (such as DataBricks) not yet supporting widgets for stable releases.

Studio can render the map in one of two ways: as a Widget or as HTML. To summarize:

Rendering MethodDescription
(Recommended) widgetMap is rendered as an interactive widget. Visually updates with API calls that alter the map's state. Best used with the sidecar widget.
htmlMap is rendered as a static HTML object. Does not update with API calls that alter the map's state. Users must call the map every time they wish to display the most updated version of the map. However, provides increased stability, rendering the entire map whenever called.

You can specify the rendering method during map creation. The following example forces HTML rendering for map:

map = create_map(renderer="html", api_key="<api-key>")


While the Studio development team provides support for all aforementioned notebook environments, we recommend JupyterLab for most use cases. In addition to providing a modular structure with an improved user interface, it exhibits the most stable widget support of all notebook environments.

With the consistent interactive widget support, you can use the recommended widget rendering method, displaying a map that updates with any changes made via the API. When used with the sidecar widget, your map can be updated in an attached window, always in view while you add new cells to your notebook.

However, html rendering can be used when experiencing artifacts or other bugs with the default widget map. As html renders are static and do not interact with the map's state, it offers more stability and accuracy, building your map from scratch whenever it is called. If your map has trouble loading we also recommend creating your map with html rendering.