Setup Guide

This page contains setup information for:

Python Setup

PyPI versionPyPI version

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

ArgumentTypeDescription
refresh_tokenstringOptional if access_token is used. A refresh token for interacting with Studio.

Keyword-only Arguments

ArgumentTypeDescription
access_tokenstringOptional if refresh_token is used. An access token for interacting with Studio.
credentials_dirUnion[str, pathlib.Path]Optional. A path to a directory containing credentials. If used, you'll need to include it every time you use the Data SDK class.

Default:
$HOME/.config/unfolded
store_credentialsbooleanOptional.
If True, tokens only need to be supplied once.
If False, tokens need to be supplied every time the Data SDK class is used.

Default: True except when run by ROOT user.

πŸ‘

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://api.unfolded.ai.

Authentication

Before using the Data SDK REST API, you must have a valid Studiorefresh 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/tokens \
  --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://api.unfolded.ai/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.


Sign In