This page contains setup information for:

• The Data SDK Python Package
• The Data SDK CLI (Command Line Interface) Package
• Data SDK via the REST API (no installation required)

Python Setup

The Studio Data SDK Python package provides support for interfacing with the Studio Data SDK from Python programs or Jupyter Notebooks.

The Python bindings provide type-safe functional wrappers around the REST APIs and additional language specific integrations (such as support for Pandas and GeoPandas in the Python Data SDK).

Installation

Install via pip:

pip install -U unfolded.data-sdk

Authentication

Before using the Data SDK, you must have a valid Studio authentication token.

To authenticate via the Python module, pass a refresh token to the DataSDK
class.

📘

Note:

The refresh token only needs to be supplied once. For future uses of the DataSDK class, do not pass a refresh_token argument.

from unfolded.data_sdk import DataSDK
DataSDK(refresh_token='v1.ABC...')

Data SDK Constructor

Create an instance of a Studio Data SDK.

Arguments

Keyword-only Arguments

👍

Recommendation:

Pass Trueto store_credentials when used on a personal computer or other secure, single-user machine.
Pass False on any multi-user system where the credentials_dir is accessible to multiple users.

CLI Setup

The Studio Data SDK CLI (Command Line Interface) provides access to the
Studio Data SDK from shell scripts.

Installation

The Studio Data SDK CLI requires that your system has a Python environment.

To install the CLI:

pip install -U unfolded.data-sdk

Authentication

Before using the Data SDK CLI, you must have a valid Studio authentication token.

To authenticate via the CLI, use the store-refresh-token method:

uf-data-sdk store-refresh-token

The CLI will then prompt for your refresh token, and print a message when it has
successfully stored it.

Note that authentication with a refresh token only needs to be done once.

Usage

The CLI is available through uf-data-sdk on the command line. Running uf-data-sdk --help
prints a list of available commands:

> uf-data-sdk --help
Usage: uf-data-sdk [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  delete-dataset       Delete dataset from Studio Warning: This...
  download-dataset     Download data for existing dataset to disk
  list-datasets        List datasets for a given user
  store-refresh-token  Store refresh token to enable seamless future...
  update-dataset       Update data for existing Studio dataset
  upload-file          Upload new dataset to Studio

To learn how use a command, pass --help to a subcommand:

> uf-data-sdk download-dataset --help

Usage: uf-data-sdk download-dataset [OPTIONS]

  Download data for existing dataset to disk

Options:
  --dataset-id TEXT       Dataset id.  [required]
  -o, --output-file PATH  Output file for dataset.  [required]
  --help                  Show this message and exit.

REST Setup

At its core, the Data SDK is a REST API that allows you to upload and update data from your own applications, including command-line interfaces, scripts, Jupyter notebooks, etc.

The Studio REST API endpoints are available at https://data-api.foursquare.com.

Authentication

Before using the Data SDK REST API, you must have a valid Studio refresh token.

To acquire an access token using a refresh token, you need to make a request to our auth server, passing the client_id for our API.

Sample cURL call:

curl -X POST https://auth.studio.foursquare.com/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'grant_type=refresh_token' \
  --data 'client_id=v970dpbcqmRtr3y9XwlAB3dycpsvNRZF' \
  --data refresh_token=<REFRESH_TOKEN>

The response is in JSON, and will include both an access_token and a refresh_token you can use when the new access token expires.

To make calls to the Studio REST API using your access token, include it in the authorization header of your requests.

Sample curl call:

curl https://https://data-api.foursquare.com/v1/datasets \
  --header 'Authorization: Bearer eyJhbGciOiJSU...'

Authentication Errors

API calls that are unauthorized, do not include a token, include an expired or malformed token, etc., will return an appropriate error in the response.

UUIDs

Maps and datasets stored on the Studio cloud can be accessed by their Universal Unique ID (UUID). Many functions throughout the Data SDK request the UUID to access both map and dataset records. For example, get_map_by_id requires users to pass a map's UUID, and download_dataset requires that users pass a dataset's UUID.

There are two ways to retrieve UUIDs for maps or datasets:

• Retrieve UUIDs from the Studio website
• Retrieve UUIDs with the Data SDK

Retrieve UUIDs from the Studio Website

UUIDs can be retrieved via the website.

1. Log in to Studio then navigate to the Workspace.

2. Click any map or dataset tile to open it. The last section of the URL is the UUID for the asset.

Note: You can also retrieve a map's URL by clicking ⋮ More Options >> Get Link on the map tile.

Retrieve UUIDs with the Data SDK

Users may also retrieve UUIDs programmatically via the Data SDK.

To retrieve maps:

datasets = data_sdk.list_datasets()

uf-data-sdk list-datasets

curl -X GET https://data-api.foursquare.com/v1/datasets HTTP/1.1 \
    -H 'Authorization: Bearer <token>'

If you are part of an organization, you can pass the organization parameter to get all dataset records for the organization of the authorized account.

datasets = data_sdk.list_datasets(organization=True)

uf-data-sdk list-datasets --organization

curl -X GET https://data-api.foursquare.com/v1/datasets/for-organization HTTP/1.1 \
    -H 'Authorization: Bearer <token>'