DataScribe API Client

datascribe_api is a Python client for interacting with the DataScribe API. It allows users to search for data tables and their metadata, automating data retrieval and analysis workflows.

Report a Bug | Request a Feature | Documentation

---

Features

• Search and retrieve data tables and metadata from the DataScribe API
• Simple Python interface for querying endpoints
• Automatic model mapping for API responses
• Context manager support for resource management

---

Installation

You can use pip to install the datascribe_api package directly from PyPI:

pip install datascribe_api

---

Quick Start

Python Client Usage

To get started with the datascribe_api, you can use the following example to retrieve and print the names of data tables available to the user:

fromdatascribe_apiimportDataScribeClientwithDataScribeClient(api_key="YOUR_API_TOKEN") asclient:
tables=client.get_data_tables_for_user()
fortableintables:
print(f"Table Name: {table.display_name}")

Make sure to replace the DataScribeClient initialization with your actual API key or store it in an environment variable named DATASCRIBE_API_TOKEN for authentication.

API Endpoints

Below is a list of all available endpoints in the DataScribe API Python client:

Endpoint Name	HTTP Path	Parameters	Description
get_data_tables	/data/data-tables	–	List all data tables (admin only)
get_data_tables_for_user	/data/data-tables-for-user	–	List data tables available to the user
get_data_table	/data/data-table	tableName, startingRow, numRows	Get rows from a data table
get_data_table_rows	/data/data-table-rows	tableName, columns, startingRow , numRows, filters	Get rows from a data table (with columns)
get_data_table_rows_count	/data/data-table-rows-count	tableName, filters	Get row count for a data table
get_data_table_columns	/data/data-table-columns	tableName	Get columns of a data table
get_data_table_metadata	/data/data-table-metadata	tableName	Get metadata for a data table
get_material_by_id	/materials	ids, providers	Get material by IDs
search_materials	/materials/search	formula, elements, exclude_elements, spacegroup, props, temperature, providers, page, size	Search for materials

---

Filtering Data with the Filter Class

The datascribe_api package provides a powerful and expressive Filter class for building complex queries in a Pythonic way. Filters can be passed to API methods as dictionaries, single Filter objects, or lists of Filter objects (for AND logic).

Basic Usage

fromdatascribe_apiimportDataScribeClientfromdatascribe_api.filterimportFilterwithDataScribeClient(api_key="YOUR_API_TOKEN") asclient:
filters=Filter("age") >30rows=client.get_data_table_rows(tableName="users", columns=["age", "name"], filters=filters)
forrowinrows:
print(row)

Supported Filter Operations

• Equality and Comparison

  Filter("age") ==25Filter("score") !=100Filter("height") >170Filter("height") >=180Filter("height") <200Filter("height") <=160

• IN and NOT IN

  Filter("status").in_(["active", "pending"])
  Filter("role").not_in(["guest", "banned"])

• LIKE and ILIKE (case-insensitive LIKE)

  Filter("name").like("%John%")
  Filter("email").ilike("%@gmail.com")

• IS NULL and IS NOT NULL

  Filter("deleted_at").is_null()
  Filter("deleted_at").is_not_null()

Combining Multiple Filters (AND logic)

You can pass a list of filters to combine them with AND logic:

filters= [
Filter("age") >18,
Filter("status") =="active",
Filter("country").in_(["US", "CA"])
]
rows=client.get_data_table_rows(tableName="users", columns=["age", "status", "country"], filters=filters)

Passing Filters as Dictionaries

You can also pass filters as plain dictionaries if you prefer:

filters= {"column": "age", "operator": ">", "value": 21}
rows=client.get_data_table_rows(tableName="users", columns=["age"], filters=filters)

---

CLI Usage

You can also use the command-line interface to interact with the DataScribe API. Here are some examples:

# List all data tables for the authenticated user
datascribe_cli data-tables-for-user

# Retrieve rows from the data table named m3gnet_mpf
datascribe_cli data-table --table-name m3gnet_mpf

See the CLI documentation for more commands and options.

---

Citation

We are currently preparing a preprint for publication. If you use datascribe_api in your research, please cite the following:

Sarıtürk, D. (2025). datascribe_api. Zenodo. https://doi.org/10.5281/zenodo.17090844

BibTeX:

@software{sariturk_2025_17518243,
author = {Sarıtürk, Doğuhan},
title = {datascribe\_api},
month = nov,
year = 2025,
publisher = {Zenodo},
doi = {10.5281/zenodo.17090844},
url = {https://doi.org/10.5281/zenodo.17090844},
}

---

License

This project is licensed under the GNU GPLv3 License. See the LICENSE file for details.