# Quanda Data

## QuandaData SDK Usage Guide

**Internal Use Only:** This documentation is intended solely for internal use within Quantit. The `QuandaData` object can be added through other internal Quantit tools, which are not covered in this documentation.

### Overview

The `QuandaData` class provides static methods to interact with the Quanda Data API. It allows users to list available data objects and retrieve specific data objects, either as files or JSON objects.

### Methods

#### `object_list(prefix='')`

Retrieves a list of available data objects. The optional `prefix` parameter can be used to filter the list based on a prefix string. If the prefix is an empty string, it will return an empty result.

**Example Usage**

```python
from finter.data import QuandaData

# not working
object_list = QuandaData.object_list("")

# Retrieve data objects with a specific prefix
filtered_object_list = QuandaData.object_list(prefix='car_ir')

# result example:
In [37]: QuandaData.object_list('car_ir')[:5]
Out[37]: 
['car_ir/hyundai/2016_hyundai_sales.xlsx',
 'car_ir/hyundai/2017_hyundai_sales.xlsx',
 'car_ir/hyundai/2018_hyundai_sales.xlsx',
 'car_ir/hyundai/2019_hyundai_sales.xlsx',
 'car_ir/hyundai/2020_hyundai_sales.xlsx']
```

#### `dir_list(prefix='')`

Retrieves a list of subdirectory names for the specified path prefix. Similar to `object_list()`, but returns only directory names instead of full paths. Note that an empty prefix (`""`) will result in an error as you cannot view all folders at once - a valid prefix path must be provided.

#### Example Usage

```python
from finter.data import QuandaData

# This will result in an error
# all_dirs = QuandaData.dir_list("")

# Retrieve subdirectories with a specific prefix
car_dirs = QuandaData.dir_list(prefix='car_ir')

# result example:
In [42]: QuandaData.dir_list('car_ir')
Out[42]: 
['hyundai',
 'kia',
 'tesla',
 'toyota',
 'volkswagen']
```

#### `get(object_name, is_file_type=False)`

Retrieves a specific data object. If `is_file_type` is set to `True`, the data is retrieved as a raw file. Otherwise, it is retrieved as a JSON object.

#### Example Usage for JSON Data

```python
import pandas as pd
from finter.data import QuandaData

# Retrieve JSON data object
data = QuandaData.get("ecos/macros/raw_df")
df = pd.read_json(data) # Convert the JSON data to a pandas DataFrame

# result example:
In [2]: df.tail(2)
Out[2]: 
	731Y003/D/0000003/?/?/?	817Y002/D/010101000/?/?/?	817Y002/D/010190000/?/?/?	817Y002/D/010200000/?/?/?	817Y002/D/010210000/?/?/?	817Y002/D/010300000/?/?/?	817Y002/D/010400001/?/?/?
2024-08-19	1334.0	NaN	3.055	2.927	2.985	3.424	3.032
2024-08-20	1333.2	NaN	3.058	2.944	2.999	3.442	3.035
```

#### `get(object_name, is_file_type=True)`

#### Example Usage for File Data

```python
import pandas as pd
from io import BytesIO
from finter.data import QuandaData
# !pip install openpyxl for read_excel with pandas if openpyxl is not installed

# Retrieve file data object
data = QuandaData.get("eis/energy_usage.xlsx", is_file_type=True)
df = pd.read_excel(BytesIO(data)) # Convert the file data to a pandas DataFrame

# result example:
In [2]: df.tail(2)
Out[2]: 

	Unnamed: 0	000050	000070	000080	000100	000120	000150	000180	000210	000270	...	316140	322000	329180	344820	353200	357780	361610	375500	376190	378850
4381	2020-12-30	8266.75602	113665.0589	45859.35008	7433.13418	85769.95494	31809.86841	14586.28857	675466.03255	323953.10695	...	14456.29537	12634.44032	2.521610e+06	232100.63259	48419.56033	22586.44804	62387.38178	853501.04158	9652.61059	9553.89807
4382	2020-12-31	8266.75602	113665.0589	45859.35008	7433.13418	85769.95494	31809.86841	14586.28857	675466.03255	323953.10695	...	14456.29537	12634.44032	2.521610e+06	232100.63259	48419.56033	22586.44804	62387.38178	853501.04158	9652.61059	9553.89807
2 rows × 433 columns
```

#### `help()`

You can use the `help()` function to check usages for creating a guide document.

```python
In [1]: from finter.data import QuandaData

In [2]: QuandaData.help()

# get file type data
# in case of loading excel file, maybe you need install openpyxl package
# ex) pip install openpyxl
import pandas as pd
from io import BytesIO
data = QuandaData.get('object_name', is_file_type=True)
df = pd.read_excel(BytesIO(data))

# get json data
import pandas as pd
data = QuandaData.get('object_name')
df = pd.read_json(data)           

```

#### Quanda Data Getting Cases

1. **Named**
   * Description: Data explicitly specified by name
   * `data = QuandaData.get(named_object_name)`
2. **Unnamed - Python Object (JSON, DataFrame, etc.)**
   * Description: Data treated as Python objects like JSON, DataFrame, etc., without a specific name
   * `data = QuandaData.get(unnamed_object_name)`
3. **Unnamed - File Type (.json, .xls, etc.)**
   * Description: Data provided as file types without a specific name
   * `data = QuandaData.get(named_object_name, is_file_type=True)`\
     `df = pd.read_excel(BytesIO(data)) # excel file(bytes) to python object(dataframe)`

### Additional Parameters

**`bucket`**

* Both `object_list` , `dir_list` and `get` methods support an optional `bucket` parameter.
* This parameter allows users to specify a logical grouping or context for the requested data.
* Usage of `bucket` enables more refined control over data retrieval within the API.



This documentation should be used as a reference for interacting with the Quanda Data API within Quantit. For any further assistance or advanced usage, please refer to internal support channels.
