rcsb-api: Python Toolkit for Accessing RCSB.org APIs

Python interface for RCSB Protein Data Bank API services at RCSB.org.

Installation

This package requires Python 3.8 or later.

Get it from PyPI:

pip install rcsb-api

Or, download from GitHub and install locally:

git clone https://github.com/rcsb/py-rcsb-api.git
cd py-rcsb-api
pip install .

Getting Started

Full documentation available at readthedocs.

The RCSB PDB Search API supports RESTful requests according to a defined schema. This package provides an rcsbapi.search module that simplifies generating complex search queries.

The RCSB PDB Data API supports requests using GraphQL, a language for API queries. This package provides an rcsbapi.data module that simplifies generating queries in GraphQL syntax.

Search API

The rcsbapi.search module supports all available Advanced Search services, as listed below. For more details on their usage, see Search Service Types.

|Search service |QueryType | |----------------------------------|--------------------------| |Full-text |TextQuery() | |Attribute (structure or chemical) |AttributeQuery() | |Sequence similarity |SeqSimilarityQuery() | |Sequence motif |SeqMotifQuery() | |Structure similarity |StructSimilarityQuery() | |Structure motif |StructMotifQuery() | |Chemical similarity |ChemSimilarityQuery() |

Search API Examples

To perform a search for all structures from humans associated with the term "Hemoglobin", you can combine a "full-text" query (TextQuery) with an "attribute" query (AttributeQuery):

```python from rcsbapi.search import AttributeQuery, TextQuery from rcsbapi.search import search_attributes as attrs

Construct a "full-text" sub-query for structures associated with the term "Hemoglobin"

q1 = TextQuery(value="Hemoglobin")

Construct an "attribute" sub-query to search for structures from humans

q2 = AttributeQuery( attribute="rcsbentitysourceorganism.scientificname", operator="exactmatch", # Other operators include "containsphrase", "exists", and more value="Homo sapiens" )

OR, do so by using Python bitwise operators:

q2 = attrs.rcsbentitysourceorganism.scientificname == "Homo sapiens"

Combine the sub-queries (can sub-group using parentheses and standard operators, "&", "|", etc.)

query = q1 & q2

Fetch the results by iterating over the query execution

for rId in query(): print(rId)

OR, capture them into a variable

results = list(query()) ```

These examples are in operator syntax. You can also make queries in fluent syntax. Learn more about both syntaxes and implementation details in Query Syntax and Execution.

Data API

The rcsbapi.data module allows you to easily construct GraphQL queries to the RCSB.org Data API.

This is done by specifying the following input: - "inputtype": the data hierarchy level you are starting from (e.g., "entry", "polymerentity", etc.) (See full list here). - "inputids": the list of IDs for which to fetch data (corresponding to the specified "inputtype") - "returndatalist": the list of data items ("fields") to retrieve. (Available fields can be explored here or via the GraphiQL editor's Documentation Explorer panel.)

Data API Examples

This is a simple query requesting the experimental method of a structure with PDB ID 4HHB (Hemoglobin).

The query must be executed using the .exec() method, which will return the JSON response as well as store the response as an attribute of the DataQuery object. From the object, you can access the Data API response, get an interactive editor link, or access the arguments used to create the query. The package is able to automatically build queries based on the "inputtype" and path segment passed into "returndata_list". If using this package in code intended for long-term use, it's recommended to use fully qualified paths. When autocompletion is being used, an WARNING message will be printed out as a reminder.

python from rcsbapi.data import DataQuery as Query query = Query( input_type="entries", input_ids=["4HHB"], return_data_list=["exptl.method"] ) print(query.exec()) Data is returned in JSON format json { "data": { "entries": [ { "rcsb_id": "4HHB", "exptl": [ { "method": "X-RAY DIFFRACTION" } ] } ] } }

Here is a more complex query. Note that periods can be used to further specify requested data in returndatalist. Also note multiple return data items and ids can be requested in one query. python from rcsbapi.data import DataQuery as Query query = Query( input_type="polymer_entities", input_ids=["2CPK_1", "3WHM_1", "2D5Z_1"], return_data_list=[ "polymer_entities.rcsb_id", "rcsb_entity_source_organism.ncbi_taxonomy_id", "rcsb_entity_source_organism.ncbi_scientific_name", "cluster_id", "identity" ] ) print(query.exec())

Jupyter Notebooks

Several Jupyter notebooks with example use cases and workflows for all package modules are provided under notebooks.

For example, one notebook using both Search and Data API packages for a COVID-19 related example is available in notebooks/searchdataworkflow.ipynb or online through Google Colab .

Citing

Please cite the rcsb-api package with the following reference:

Dennis W. Piehl, Brinda Vallat, Ivana Truong, Habiba Morsy, Rusham Bhatt, Santiago Blaumann, Pratyoy Biswas, Yana Rose, Sebastian Bittrich, Jose M. Duarte, Joan Segura, Chunxiao Bi, Douglas Myers-Turnbull, Brian P. Hudson, Christine Zardecki, Stephen K. Burley. rcsb-api: Python Toolkit for Streamlining Access to RCSB Protein Data Bank APIs, Journal of Molecular Biology, 2025. DOI: 10.1016/j.jmb.2025.168970

You should also cite the RCSB.org API services this package utilizes:

Yana Rose, Jose M. Duarte, Robert Lowe, Joan Segura, Chunxiao Bi, Charmi Bhikadiya, Li Chen, Alexander S. Rose, Sebastian Bittrich, Stephen K. Burley, John D. Westbrook. RCSB Protein Data Bank: Architectural Advances Towards Integrated Searching and Efficient Access to Macromolecular Structure Data from the PDB Archive, Journal of Molecular Biology, 2020. DOI: 10.1016/j.jmb.2020.11.003

Documentation and Support

Please refer to the readthedocs page to learn more about package usage and other available features as well as to see more examples.

If you experience any issues installing or using the package, please submit an issue on GitHub and we will try to respond in a timely manner.