This page contains setup information for:

- [The Data SDK Python Package](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#python-setup)
- [The Data SDK CLI (Command Line Interface) Package](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#cli-setup)
- Data SDK via the [REST API](https://docs.foursquare.com/developer/docs/studio-data-sdk-get-started#rest-setup) (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:

```shell
pip install -U foursquare.data-sdk
```

## Authentication

Before using the Data SDK, you must have a valid Studio [authentication token](https://docs.foursquare.com/developer/docs/studio-authentication).

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.

```python
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.<br>Default:<br>`$HOME/.config/foursquare` |
| `store_credentials`| `boolean`                | Optional.<br>If `True`, tokens only need to be supplied once.<br>If `False`, tokens need to be supplied every time the Data SDK class is used.<br>Default: `True` except when run by `ROOT` user. |

> 👍
> ### Recommendation:
> Pass `True` to `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:

```shell
pip install -U foursquare.data-sdk
```

## Authentication

Before using the Data SDK CLI, you must have a valid Studio [authentication token](https://docs.foursquare.com/developer/docs/studio-authentication).

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

```shell
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:

```shell
> 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 to use a command, pass `--help` to a subcommand:

```shell
> 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](https://data-api.foursquare.com/).

## Authentication

Before using the Data SDK REST API, you must have a valid Studio [refresh token](https://docs.foursquare.com/developer/docs/studio-authentication#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
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
curl 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`](https://docs.foursquare.com/developer/docs/data-sdk-map-functions#get-map) requires users to pass a map's UUID, and [`download_dataset`](https://docs.foursquare.com/developer/docs/data-sdk-data-functions#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](https://studio.foursquare.com/workspace/maps/user).
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:

```python
datasets = data_sdk.list_datasets()
```

```shell
fsq-data-sdk list-datasets
```

```http
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.

```python
datasets = data_sdk.list_datasets(organization=True)
```

```shell
fsq-data-sdk list-datasets --organization
```

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