API Documentation

class rcsbapi.model.ModelQuery(encoding: Optional[Literal['cif', 'bcif', 'sdf', 'mol', 'mol2']] = 'cif', file_directory: Optional[str] = None, download: Optional[bool] = False, compress_gzip: Optional[bool] = False, max_retries: Optional[int] = None, retry_backoff: Optional[int] = None)

Class for querying model data from the RCSB ModelServer.

Supports various query types such as full structure retrieval, ligand queries, atom-level queries, and contextual residue or ligand information. Handles output formats, optional file saving, and gzip compression.

__init__(encoding: Optional[Literal['cif', 'bcif', 'sdf', 'mol', 'mol2']] = 'cif', file_directory: Optional[str] = None, download: Optional[bool] = False, compress_gzip: Optional[bool] = False, max_retries: Optional[int] = None, retry_backoff: Optional[int] = None)

Query object for Model Server API requests.

Parameters

  • encoding (str, optional) – Default encoding format to use for all requests. Defaults to “cif”.

  • file_directory (str, optional) – Default file directory to use for all requests. Defaults to current working directory.

  • download (bool, optional) – Default download flag to use for all requests. Defaults to False.

  • compress_gzip (bool, optional) – Default setting for GZIP compression to use for all requests. Defaults to False.

  • max_retries (int, optional) – Default number of max retries to perform for all requests. Defaults to config.MAX_RETRIES.

  • retry_backoff (int, optional) – Default retry backoff delay to wait between failed requets. Defaults to config.RETRY_BACKOFF.

get_assembly(entry_id: str, name: Optional[str] = '1', model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Fetches information about molecular assemblies.

get_atoms(entry_id: str, label_entity_id: Optional[str] = None, label_asym_id: Optional[str] = None, auth_asym_id: Optional[str] = None, label_comp_id: Optional[str] = None, auth_comp_id: Optional[str] = None, label_seq_id: Optional[int] = None, auth_seq_id: Optional[int] = None, pdbx_PDB_ins_code: Optional[str] = None, label_atom_id: Optional[str] = None, auth_atom_id: Optional[str] = None, type_symbol: Optional[str] = None, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Fetches atom-level details.

get_full_structure(entry_id: str, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Retrieve the full atomic model of a specified entry from the ModelServer.

Parameters

  • entry_id (str) – The PDB ID of the structure to retrieve.

  • model_nums (Optional[List[int]]) – List of model numbers to include (if multiple models exist).

  • encoding (Optional[Literal["cif", "bcif"]]) – Format of the returned file (default is “cif”).

  • copy_all_categories (Optional[bool]) – If True, copies all data categories; otherwise, uses minimal.

  • data_source (Optional[str]) – Optional data source name.

  • transform (Optional[str]) – Transformation matrix to apply to coordinates.

  • download (Optional[bool]) – If True, downloads and saves the file to disk.

  • filename (Optional[str]) – Custom filename to use if downloading.

  • file_directory (Optional[str]) – Directory where file will be saved.

  • compress_gzip (Optional[bool]) – If True, compress the output file using GZIP.

get_ligand(entry_id: str, label_entity_id: Optional[str] = None, label_asym_id: Optional[str] = None, auth_asym_id: Optional[str] = None, label_comp_id: Optional[str] = None, auth_comp_id: Optional[str] = None, label_seq_id: Optional[int] = None, auth_seq_id: Optional[int] = None, pdbx_PDB_ins_code: Optional[str] = None, label_atom_id: Optional[str] = None, auth_atom_id: Optional[str] = None, type_symbol: Optional[str] = None, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif', 'sdf', 'mol', 'mol2']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Retrieves ligand-related information, including components and interactions.

Parameters

  • entry_id (str) – The PDB ID of the structure.

  • label_entity_id (str, optional) – Entity identifier using label nomenclature.

  • label_asym_id (str, optional) – Asymmetric unit ID using label nomenclature.

  • auth_asym_id (str, optional) – Asymmetric unit ID using author-provided nomenclature.

  • label_comp_id (str, optional) – Ligand component ID using label nomenclature.

  • auth_comp_id (str, optional) – Ligand component ID using author nomenclature.

  • label_seq_id (int, optional) – Residue sequence number (label nomenclature).

  • auth_seq_id (int, optional) – Residue sequence number (author nomenclature).

  • pdbx_PDB_ins_code (str, optional) – Insertion code for distinguishing alternate residue IDs.

  • label_atom_id (str, optional) – Atom name using label nomenclature.

  • auth_atom_id (str, optional) – Atom name using author nomenclature.

  • type_symbol (str, optional) – Atomic element symbol (e.g., “C”, “N”, “O”).

  • model_nums (List[int], optional) – Specific model numbers to retrieve.

  • encoding (str, optional) – Output format, one of: “cif”, “sdf”, “mol”, “mol2”, “bcif”.

  • copy_all_categories (bool, optional) – Whether to include all data categories in the output.

  • data_source (str, optional) – Source of the structure data.

  • transform (str, optional) – Transformation ID for biological assemblies or specific views.

  • download (bool, optional) – If True, save the result to disk.

  • filename (str, optional) – Custom filename for saving the output.

  • file_directory (str, optional) – Directory path to save the output file.

  • compress_gzip (bool, optional) – If True, compress the file using gzip.

get_multiple_structures(entry_ids: List[str], query_type: Literal['full', 'ligand', 'atoms', 'residue_interaction', 'residue_surroundings', 'surrounding_ligands', 'symmetry_mates', 'assembly'], **kwargs)

Fetch multiple structures at once based on a list of entry_ids.

Parameters

  • entry_ids (List[str]) – List of structure IDs to query.

  • query_type (str) – The type of query to execute (e.g., “full”, “ligand”, etc.).

  • **kwargs – Additional query parameters to pass to the API.

Returns

A dictionary with entry IDs as keys and the corresponding responses as values.

Return type

dict

get_residue_interaction(entry_id: str, label_entity_id: Optional[str] = None, label_asym_id: Optional[str] = None, auth_asym_id: Optional[str] = None, label_comp_id: Optional[str] = None, auth_comp_id: Optional[str] = None, label_seq_id: Optional[int] = None, auth_seq_id: Optional[int] = None, pdbx_PDB_ins_code: Optional[str] = None, label_atom_id: Optional[str] = None, auth_atom_id: Optional[str] = None, type_symbol: Optional[str] = None, radius: Optional[float] = 5.0, assembly_name: Optional[str] = None, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Retrieves data on interactions between residues.

get_residue_surroundings(entry_id: str, label_entity_id: Optional[str] = None, label_asym_id: Optional[str] = None, auth_asym_id: Optional[str] = None, label_comp_id: Optional[str] = None, auth_comp_id: Optional[str] = None, label_seq_id: Optional[int] = None, auth_seq_id: Optional[int] = None, pdbx_PDB_ins_code: Optional[str] = None, label_atom_id: Optional[str] = None, auth_atom_id: Optional[str] = None, type_symbol: Optional[str] = None, radius: Optional[float] = 5.0, assembly_name: Optional[str] = None, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Provides information about residues surrounding a given structure.

get_surrounding_ligands(entry_id: str, label_entity_id: Optional[str] = None, label_asym_id: Optional[str] = None, auth_asym_id: Optional[str] = None, label_comp_id: Optional[str] = None, auth_comp_id: Optional[str] = None, label_seq_id: Optional[int] = None, auth_seq_id: Optional[int] = None, pdbx_PDB_ins_code: Optional[str] = None, label_atom_id: Optional[str] = None, auth_atom_id: Optional[str] = None, type_symbol: Optional[str] = None, omit_water: Optional[bool] = False, radius: Optional[float] = 5.0, assembly_name: Optional[str] = None, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Provides information about ligands surrounding a given structure.

get_symmetry_mates(entry_id: str, radius: Optional[float] = 5.0, model_nums: Optional[List[int]] = None, encoding: Optional[Literal['cif', 'bcif']] = None, copy_all_categories: Optional[bool] = False, data_source: Optional[str] = None, transform: Optional[str] = None, download: Optional[bool] = None, filename: Optional[str] = None, file_directory: Optional[str] = None, compress_gzip: Optional[bool] = None)

Retrieves symmetry-related data.