Setup Guide - Data SDK
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 foursquare.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 arefresh_token
argument.
from foursquare.data_sdk import DataSDK
DataSDK(refresh_token='v1.ABC...')
Data SDK Constructor
Create an instance of a Studio Data SDK.
Arguments
Argument | Type | Description |
---|---|---|
refresh_token | string | Optional if access_token is used. A refresh token for interacting with Studio. |
Keyword-only Arguments
Argument | Type | Description |
---|---|---|
access_token | string | Optional if refresh_token is used. An access token for interacting with Studio. |
credentials_dir | Union[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/foursquare |
store_credentials | boolean | Optional. 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
True
tostore_credentials
when used on a personal computer or other secure, single-user machine.
PassFalse
on any multi-user system where thecredentials_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 foursquare.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:
fsq-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 fsq-data-sdk
on the command line. Running fsq-data-sdk --help
prints a list of available commands:
> fsq-data-sdk --help
Usage: fsq-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:
> fsq-data-sdk download-dataset --help
Usage: fsq-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()
fsq-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)
fsq-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 3 months ago