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 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).
Install via pip:
pip install -U unfolded.data-sdk
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
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 a Studio Data SDK.
|Optional if |
|Optional if |
|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 Studio Data SDK CLI (Command Line Interface) provides access to the
Studio Data SDK from shell scripts.
The Studio 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 Studio 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 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.
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.
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.
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.
curl https://https://data-api.foursquare.com/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.
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
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.
Users may also retrieve UUIDs programmatically via the Data SDK.
To retrieve maps:
datasets = 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>'
Updated 5 months ago