This page shows how to use the Studio APIs in Python notebooks.

Before starting, make sure you have followed installation instructions for your Notebook environment.

To learn more, please visit Foursquare's developer documentation, which contains complete documentation for both the Map SDK and Data SDK.

Authentication

Before using the Data SDK, you must have a valid authenticate to Studio. To do so, simply type the following command into your command line.

$ uf-data-sdk authenticate

Alternatively, visit https://studio.foursquare.com/tokens.html to retrieve your tokens.

Import

Once installed in your Python environment or Notebook, the Python package can be imported via unfolded.data_sdk:

from unfolded.data_sdk import DataSDK, MediaType

data_sdk = DataSDK()

List Datasets

List datasets for given user

datasets = data_sdk.list_datasets()

Get Dataset by ID

Get dataset record given its id

dataset = datasets[0]
data_sdk.get_dataset_by_id(dataset)

Download dataset data

Download data for dataset given its id

dataset = datasets[0]
data_sdk.download_dataset(dataset, output_file='output.csv')

Download dataset data to a pandas DataFrame or GeoPandas GeoDataFrame

If the dataset is a CSV file, a pandas DataFrame will be returned. If it isa GeoJSON file, a GeoPandas GeoDataFrame will be returned.

dataset = datasets[0]
dataframe = data_sdk.download_dataframe(dataset)

Upload new dataset

To upload a new dataset to Foursquare Studio, use upload_file.

data_sdk.upload_file(
    file='new_file.csv',
    name='Dataset name',
    media_type=MediaType.CSV,
    description='Dataset description')

To upload a DataFrame to Foursquare Studio, use upload_dataframe. This method supports both Pandas DataFrame objects and GeoPandas GeoDataFrame objects.

data_sdk.upload_dataframe(
    dataframe,
    name='Dataset name',
    description='Dataset description')

Update existing dataset

To update data for an existing Foursquare Studio dataset, pass a dataset keyword
argument to upload_file.

dataset = datasets[0]
data_sdk.upload_file(
    file='new_file.csv',
    dataset=dataset,
    media_type=MediaType.CSV)

To update data for an existing Studio dataset using a DataFrame, pass a dataset keyword argument to upload_dataframe.

data_sdk.upload_dataframe(
    dataframe,
    dataset=dataset,
    name='Dataset name',
    description='Dataset description')

Delete dataset

Delete dataset from Foursquare Studio

Warning: This operation cannot be undone. If you delete a dataset
currently used in one or more maps, the dataset will be removed from
those maps, possibly causing them to render incorrectly.

dataset = datasets[0]
data_sdk.delete_dataset(dataset)

Embedding a map

To embed a published Studio map in Jupyter use the following code:

from foursquare.map_sdk import create_map
map = create_map(api_key="<api-key>")
map