API Documentation

RCSB PDB Data API

class rcsbapi.data.DataQuery(input_type: str, input_ids: Union[List[str], Dict[str, str], Dict[str, List[str]], List[int]], return_data_list: List[str], add_rcsb_id: bool = True, suppress_autocomplete_warning: bool = False)

Class for Data API queries.

__init__(input_type: str, input_ids: Union[List[str], Dict[str, str], Dict[str, List[str]], List[int]], return_data_list: List[str], add_rcsb_id: bool = True, suppress_autocomplete_warning: bool = False)

Query object for Data API requests.

Parameters

  • input_type (str) – query input type (e.g., “entry”, “polymer_entity_instance”, etc.)

  • input_ids (list or dict) – list (or singular dict) of ids for which to request information (e.g., [“4HHB”, “2LGI”])

  • return_data_list (list) – list of data to return (field names) (e.g., [“rcsb_id”, “exptl.method”])

  • add_rcsb_id (bool, optional) – whether to automatically add <input_type>.rcsb_id to queries. Defaults to True.

exec(batch_size: Optional[int] = None, progress_bar: bool = False, max_retries: Optional[int] = None, retry_backoff: Optional[int] = None, max_concurrency: Optional[int] = None) → Union[Dict[str, Any], Coroutine[Any, Any, Dict[str, Any]]]

POST a GraphQL query and get response concurrently using httpx.

Parameters

  • batch_size (int, optional) – size of ID batches to split up input ID list into and perform sub-requests. Defaults to config.DATA_API_BATCH_ID_SIZE. Max value: 1000.

  • progress_bar (bool, optional) – display a progress bar when executing query. Defaults to False.

  • max_retries (int, optional) – maximum number of retries to attempt for each individual sub-request (in case of timeouts or errors). Defaults to config.MAX_RETRIES.

  • retry_backoff (int, optional) – delay in seconds to wait for each retry. Defaults to config.RETRY_BACKOFF.

  • max_concurrency (int, optional) – maximum number of sub-requests to run concurrently. Defaults to config.DATA_API_MAX_CONCURRENT_REQUESTS.

Returns

JSON object containing the compiled query result (aggregated across all sub-requests) OR: Coroutine: If this is run via Jupyter with Python 3.14+, a coroutine is returned which must be awaited

Return type

Dict[str, Any]

get url to interactive GraphiQL editor

Returns

GraphiQL url

Return type

str

get_input_ids() → List[str]

get input_ids used to make query

Returns

input id list or dictionary

Return type

Union[List[str], Dict[str, List[str]], Dict[str, str]]

get_input_type() → str

get input_type used to make query

Returns

input_type

(e.g., “entry”, “polymer_entity_instance”, etc.)

Return type

str

get_query() → str

get GraphQL query

Returns

query in GraphQL syntax

Return type

str

get_response() → Union[None, Dict[str, Any]]

get JSON response to executed query

Returns

JSON object

Return type

Dict[str, Any]

get_return_data_list() → List[str]

get return_data_list used to make query

Returns

return_data_list

(e.g., [“rcsb_id”, “exptl.method”])

Return type

List[str]

class rcsbapi.data.DataSchema
__init__() → None
construct_query(input_type: str, input_ids: Union[List[str], Dict[str, str], Dict[str, List[str]]], return_data_list: List[str], add_rcsb_id: bool = True, suppress_autocomplete_warning: bool = False) → Dict[str, Any]

Construct a GraphQL query in JSON format

Parameters

  • input_ids (Union[List[str], Dict[str, str], Dict[str, List[str]]]) – identifying information for the specific entry, chemical component, etc to query

  • input_type (str) – specifies where you are starting your query. These are specific fields like “entry” or “polymer_entity_instance”.

  • return_data_list (List[str]) – requested data, can be field name(s) or dot-separated field names ex: “cluster_id” or “exptl.method”

  • add_rcsb_id (bool) – automatically request rcsb_id at the top of the query. Default is True.

  • suppress_autocomplete_warning (bool, optional) – Whether to suppress warning when autocompletion of paths is used. Defaults to False.

Returns

dictionary of format - {“query”: <query in GraphQL syntax>}

Return type

Dict[str, Any]

fetch_schema() → Dict[str, Any]

Get the JSON schema defining the Data API. Fallback to local file if necessary.

Returns

JSON schema for Data API

Return type

Dict[str, Any]

find_field_names(search_string: str) → List[str]

Find field names that fully or partially match the search string.

Parameters

search_string (str) – string to search field names for

Raises

  • ValueError – thrown when a type other than string is passed in for search_string

  • ValueError – thrown when no fields match search_string

Returns

list of matching field names

Return type

List[str]