dratio.Client#

class dratio.Client(key: str | None = None, env_name: str = 'DRATIO_KEY', base_url: str | None = None, use_persistent_session: bool = False)#

Client to interact with dratio.io API

Parameters:

key (str, optional) – API key to access dratio.io API. You can obtain your API key at https://dratio.io/app/api/. Please, keep this key in a safe place. If not specified, the key is read from the environment variable with name defined in env_name.
env_name (str, optional) – Name of the environment variable where the API key is stored. Only used if key is not specified. Defaults to ‘DRATIO_KEY’.
base_url (str, optional) – Base URL of the dratio.io API. Defaults to ‘https://api.dratio.io/api/’. Parameter used for custom deployments of dratio.io.
use_persistent_session (bool, optional) – If True, the client will use a persistent session to perform requests to the API. This is useful to reuse the same connection for multiple requests using a connection pool (for advanced use cases). If False, a new session is created for each request. Defaults to False.

Examples

Retrieve datasets available in the dratio.io marketplace as a pandas dataframe:

>>> from dratio import Client
>>> client = Client(key='<your_api_key>')
>>> df_datasets = client.get_datasets()

Retrieve a dataset from the dratio.io marketplace:

>>> dataset = client.get(code='unemployment-municipality')
>>> dataset
Dataset('unemployment-municipality')

Access fields included in the metadata of the dataset:

>>> dataset["description"]
'Monthly data on the number of unemployed persons by municipality, ...'

Download a dataset as a pandas dataframe:

>>> df = dataset.to_pandas()

__init__(key: str | None = None, env_name: str = 'DRATIO_KEY', base_url: str | None = None, use_persistent_session: bool = False) → Client#: Initializes the Client object

Methods

`__init__`([key, env_name, base_url, ...])	Initializes the Client object
`get`(code[, version, kind])	Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.
`get_dataset`(code[, version])	Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.
`get_feature`(code)	Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.
`get_file`(code)	Returns a File object with the information associated with a dataset stored file through which the information can be downloaded.
`get_publisher`(code)	Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.
`info`()
`list`([kind, format])	List a resource from the dratio.io marketplace.
`list_datasets`([format, publisher, license])	Returns a dataframe or a list with information of the datasets available in the dratio.io marketplace.
`list_features`([format, dataset, publisher, ...])	Returns a dataframe or a list with information of the features available in the dratio.io marketplace.
`list_publishers`([format, license])	Returns a dataframe or a list with information of the features available in the dratio.io marketplace.

Attributes

BASE_URL

get(code: str, version: str = None, kind: Literal['dataset', 'feature', 'file', 'publisher', 'version', 'category', 'scope', 'unit', 'publisher-type', 'data-level', 'license', 'license-item'] = 'dataset') → DatabaseResource#

Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.

Parameters:

code (str) – Unique identificador for a dataset in the database. Codes can be searched in the dratio.io marketplace or by using get_datasets.
version (str, optional) – Version of the object to retrieve. If not specified, the latest version is retrieved. Defaults to None.
kind (Literal["dataset", "feature", "publisher"]) – Kind of object to retrieve. Defaults to “dataset”.

Returns:

If kind==’dataset’, returns a Dataset object with the information associated with the dataset through which the information can be downloaded. If kind==’feature’, returns a Feature object with the information associated with the feature through which the information can be downloaded. If kind==’publisher’, returns a Publisher object with the information associated with the publisher through which the information can be downloaded.

Return type:

Union[Dataset, Feature]

Examples

Retrieve a dataset from the dratio.io marketplace:

>>> from dratio import Client
>>> client = Client('Your API key')
>>> dataset = client.get(code='municipalities')
>>> dataset
Dataset('municipalities')

Download a dataset as a pandas dataframe:

>>> df_municipalities = dataset.to_pandas()

Retrieve a publisher from the dratio.io marketplace:

>>> publisher = client.get(code='ine', kind='publisher')
>>> publisher
Publisher('ine')

Get the datasets published by the INE:

>>> datasets = publisher.list_datasets()

Raises:: ValueError – If kind is not ‘dataset’, ‘feature’ or ‘publisher’.

get_dataset(code: str, version: str | None = None) → Dataset#

Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.

Parameters:: code (str) – Unique identificador for a dataset in the database. Codes can be searched in the dratio.io marketplace or by using get_datasets.
Returns:: Dataset object with the information associated with the dataset through which the information can be downloaded.
Return type:: Dataset

get_feature(code: str) → Feature#

Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.

Parameters:: code (str) – Unique identificador for a dataset in the database. Codes can be searched in the dratio.io marketplace or by using get_datasets.
Returns:: Dataset object with the information associated with the dataset through which the information can be downloaded.
Return type:: Dataset

get_file(code: str) → File#

Returns a File object with the information associated with a dataset stored file through which the information can be downloaded.

Parameters:: code (str) – Unique identificador for a file in the database. Codes can be searched in the dratio.io marketplace or by using list_files methods of a dataset.
Returns:: Dataset object with the information associated with the dataset through which the information can be downloaded.
Return type:: Dataset

get_publisher(code: str)#

Returns a Dataset object with the information associated with the dataset through which the information can be downloaded.

Parameters:: code (str) – Unique identificador for a dataset in the database. Codes can be searched in the dratio.io marketplace or by using get_datasets.
Returns:: Dataset object with the information associated with the dataset through which the information can be downloaded.
Return type:: Dataset

list(kind: Literal['dataset', 'feature', 'file', 'publisher', 'version', 'category', 'scope', 'unit', 'publisher-type', 'data-level', 'license', 'license-item'] = 'dataset', format: Literal['pandas', 'json', 'api'] = 'pandas', **kwargs) → pd.DataFrame | List[Dict[str, Any]] | List[DatabaseResource]#

List a resource from the dratio.io marketplace.

This method is generic and can be used to list any resource from the dratio.io marketplace. The resource to list can be specified with the kind parameter. The available resources are:

dataset: List datasets.
feature: List features.
publisher: List publishers.
file: List files.
version: List versions.

The main objects of Dratio are Dataset, Publisher, Feature and File. These objects can be listed with their corresponding methods: list_datasets, list_publishers, list_features and list_files.

Parameters:

kind (Literal['dataset', 'feature', 'publisher', 'file', 'version'], optional) – Kind of resource to list.
format (Literal['pandas', 'json', 'api'], optional) – Format of the output. Defaults to ‘pandas’.
**kwargs – Additional parameters to filter the resources.

Returns:

List of resources available in the dratio.io marketplace, as a pandas dataframe, a list of dictionaries or a list of DatabaseResource objects depending on the value of format.

Return type:

Union[pd.DataFrame, List[Dict[str, Any]], List[DatabaseResource]]

Raises:

ValueError – If kind is not an available resource.
HTTPError – In case of any error when performing the request to the API.

Examples

>>> from dratio import Client
>>> client = Client('Your API key')

List datasets as a pandas dataframe:

>>> df_datasets = client.list(kind='dataset', format='pandas')

List features as a list of dictionaries:

>>> features = client.list(kind='feature', format='json')

List publishers as a list of Publisher objects:

>>> publishers = client.list(kind='publisher', format='api')

list_datasets(format: Literal['pandas', 'json', 'api'] = 'pandas', publisher: str | None = None, license: str | None = None) → pd.DataFrame | List[Dict[str, Any]] | List[Dataset]#

Returns a dataframe or a list with information of the datasets available in the dratio.io marketplace.

Parameters:

format (Literal['pandas', 'json'], optional) – Format of the output. Defaults to ‘pandas’.

Returns:

List of datasets available in the dratio.io marketplace, as a pandas dataframe or a list of dictionaries depending on the value of format.

Return type:

Union[pd.DataFrame, List[Dict[str, Any]]]

Raises:

ValueError – If format is not ‘pandas’ or ‘json’.
HTTPError – In case of any error when performing the request to the API.

Examples

>>> from dratio import Client
>>> client = Client("Your API key")

List all datasets as a pandas dataframe:

>>> df_datasets = client.list_datasets()

List all datasets of a publisher:

>>> df_datasets = client.list_datasets(publisher="ine")

Returns a dataframe or a list with information of the features available in the dratio.io marketplace.

Parameters:

format (Literal['pandas', 'json'], optional) – Format of the output. Defaults to ‘pandas’.

Returns:

List of datasets available in the dratio.io marketplace, as a pandas dataframe or a list of dictionaries depending on the value of format.

Return type:

Union[pd.DataFrame, List[Dict[str, Any]]]

Raises:

ValueError – If format is not ‘pandas’ or ‘json’.
HTTPError – In case of any error when performing the request to the API.

Examples

>>> from dratio import Client
>>> client = Client("Your API key")
>>> df_features = client.list_features()

list_publishers(format: Literal['pandas', 'json', 'api'] = 'pandas', license: str | None = None) → pd.DataFrame | List[Dict[str, Any]] | List[Publisher]#

Returns a dataframe or a list with information of the features available in the dratio.io marketplace.

Parameters:

format (Literal['pandas', 'json'], optional) – Format of the output. Defaults to ‘pandas’.

Returns:

List of features available in the dratio.io marketplace, as a pandas dataframe or a list of dictionaries depending on the value of format.

Return type:

Union[pd.DataFrame, List[Dict[str, Any]]]

Raises:

ValueError – If format is not ‘pandas’ or ‘json’.
HTTPError – In case of any error when performing the request to the API.

Examples

>>> from dratio import Client
>>> client = Client("Your API key")
>>> df_publishers = client.list_publishers()