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)
The Unfolded Data SDK Python package provides support for interfacing with the Unfolded 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).
Install via pip:
pip install -U unfolded.data-sdk
Before using the Data SDK, you must have a valid Unfolded authentication token.
To authenticate via the Python module, pass a refresh token to the
The refresh token only needs to be supplied once. For future uses of the
DataSDKclass, do not pass a
from unfolded.data_sdk import DataSDK DataSDK(refresh_token='v1.ABC...')
Create an instance of an Unfolded Data SDK.
Optional. A path to a directory containing credentials. If used, you'll need to include it every time you use the Data SDK class.
store_credentialswhen used on a personal computer or other secure, single-user machine.
Falseon any multi-user system where the
credentials_diris accessible to multiple users.
The Unfolded Data SDK CLI (Command Line Interface) provides access to the
Unfolded Data SDK from shell scripts.
The Unfolded Data SDK CLI requires that your system has a Python environment.
To install the CLI:
pip install -U unfolded.data-sdk
Before using the Data SDK CLI, you must have a valid Unfolded authentication token.
To authenticate via the CLI, use the
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.
The CLI is available through
uf-data-sdk on the command line. Running
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 Unfolded 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 Unfolded Studio dataset upload-file Upload new dataset to Unfolded 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.
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 Unfolded REST API endpoints are available at https://api.unfolded.ai.
Before using the Data SDK REST API, you must have a valid Unfolded 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.
curl -X POST https://auth.unfolded.ai/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 Unfolded REST API using your access token, include it in the
authorization header of your requests.
curl https://api.unfolded.ai/v1/datasets \ --header 'Authorization: Bearer eyJhbGciOiJSU...'
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.
Updated about 1 month ago