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

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

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

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

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.

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.