Skip to content
Research Agent Skillsby Kalaris Labs
Install
Scientific Databasesv1.4AdaptedGPLv3 license

bioservices

Unified Python interface to 40+ bioinformatics services. Use when querying multiple databases (UniProt, KEGG, ChEMBL, Reactome) in a single workflow with consistent API. Best for cross-database analysis, ID mapping across services. For quick single-database lookups use gget; for sequence/file manipulation use biopython.

Install this skill

Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and 70+ other harnesses.

skills.sh CLI (Recommended)
npx skills add KalarisLabs/research-agent-skills --skill bioservices
uvx (Python tool runner)
uvx research-agent-skills install bioservices

Documentation & Instructions

BioServices

Overview

BioServices is a Python package providing programmatic access to approximately 40 bioinformatics web services and databases. Retrieve biological data, perform cross-database queries, map identifiers, analyze sequences, and integrate multiple biological resources in Python workflows. The package handles both REST and SOAP/WSDL protocols transparently.

Version note: Examples target bioservices 1.16.0 (PyPI, Mar 2026). Requires Python 3.9–3.12. UniProt REST changes in mid-2022 (bioservices ≥1.10) mainly affect tabular columns names — see upstream _legacy_names if parsing breaks. ChEMBL wrappers changed at 1.6.0 (2018 API); use get_similarity, get_substructure, get_molecule instead of pre-1.6 method names.

When to Use This Skill

This skill should be used when:

  • Retrieving protein sequences, annotations, or structures from UniProt, PDB, Pfam
  • Analyzing metabolic pathways and gene functions via KEGG or Reactome
  • Searching compound databases (ChEBI, ChEMBL, PubChem) for chemical information
  • Converting identifiers between different biological databases (KEGG↔UniProt, compound IDs)
  • Running sequence similarity searches (BLAST, MUSCLE alignment)
  • Querying gene ontology terms (QuickGO, GO annotations)
  • Accessing protein-protein interaction data (PSICQUIC, IntactComplex)
  • Mining genomic data (BioMart, ArrayExpress, ENA)
  • Integrating data from multiple bioinformatics resources in a single workflow

Core Capabilities

1. Protein Analysis

Retrieve protein information, sequences, and functional annotations:

from bioservices import UniProt

u = UniProt(verbose=False)

# Search for protein by name
results = u.search("ZAP70_HUMAN", frmt="tab", columns="id,genes,organism")

# Retrieve FASTA sequence
sequence = u.retrieve("P43403", "fasta")

# Map identifiers between databases
kegg_ids = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")

Key methods:

  • search(): Query UniProt with flexible search terms
  • retrieve(): Get protein entries in various formats (FASTA, XML, tab)
  • mapping(): Convert identifiers between databases

Reference: references/services_reference.md for complete UniProt API details.

2. Pathway Discovery and Analysis

Access KEGG pathway information for genes and organisms:

from bioservices import KEGG

k = KEGG()
k.organism = "hsa"  # Set to human

# Search for organisms
k.lookfor_organism("droso")  # Find Drosophila species

# Find pathways by name
k.lookfor_pathway("B cell")  # Returns matching pathway IDs

# Get pathways containing specific genes
pathways = k.get_pathway_by_gene("7535", "hsa")  # ZAP70 gene

# Retrieve and parse pathway data
data = k.get("hsa04660")
parsed = k.parse(data)

# Extract pathway interactions
interactions = k.parse_kgml_pathway("hsa04660")
relations = interactions['relations']  # Protein-protein interactions

# Convert to Simple Interaction Format
sif_data = k.pathway2sif("hsa04660")

Key methods:

  • lookfor_organism(), lookfor_pathway(): Search by name
  • get_pathway_by_gene(): Find pathways containing genes
  • parse_kgml_pathway(): Extract structured pathway data
  • pathway2sif(): Get protein interaction networks

Reference: references/workflow_patterns.md for complete pathway analysis workflows.

3. Compound Database Searches

Search and cross-reference compounds across multiple databases:

from bioservices import KEGG, UniChem

k = KEGG()

# Search compounds by name
results = k.find("compound", "Geldanamycin")  # Returns cpd:C11222

# Get compound information with database links
compound_info = k.get("cpd:C11222")  # Includes ChEBI links

# Cross-reference KEGG → ChEMBL using UniChem
u = UniChem()
chembl_id = u.get_compound_id_from_kegg("C11222")  # Returns CHEMBL278315

Version caveat: the per-source get_compound_id_from_* helpers are gone from bioservices 1.16.0 — check hasattr(u, "get_compound_id_from_kegg") first, and otherwise use the current UniChem API (u.get_compounds(compound, source_type) and read res["compounds"][0]["sources"]). ChEMBL lookups follow the same rule: get_molecule, not the pre-1.6 get_compound_by_chemblId.

Common workflow:

  1. Search compound by name in KEGG
  2. Extract KEGG compound ID
  3. Use UniChem for KEGG → ChEMBL mapping
  4. ChEBI IDs are often provided in KEGG entries

Reference: references/identifier_mapping.md for complete cross-database mapping guide.

4. Sequence Analysis

Run BLAST searches and sequence alignments. NCBI requires a contact email — prefer the NCBI_EMAIL environment variable (same convention as BioPython Entrez and other repo skills):

import os
from bioservices import NCBIblast

s = NCBIblast(verbose=False)
email = os.environ["NCBI_EMAIL"]  # set before running: export NCBI_EMAIL=you@lab.org

# Run BLASTP against UniProtKB
jobid = s.run(
    program="blastp",
    sequence=protein_sequence,
    stype="protein",
    database="uniprotkb",
    email=email,
)

# Check job status and retrieve results
s.getStatus(jobid)
results = s.getResult(jobid, "out")

Note: BLAST jobs are asynchronous. Check status before retrieving results.

5. Identifier Mapping

Convert identifiers between different biological databases:

from bioservices import UniProt, KEGG

# UniProt mapping (many database pairs supported)
u = UniProt()
results = u.mapping(
    fr="UniProtKB_AC-ID",  # Source database
    to="KEGG",              # Target database
    query="P43403"          # Identifier(s) to convert
)

# KEGG gene ID → UniProt
kegg_to_uniprot = u.mapping(fr="KEGG", to="UniProtKB_AC-ID", query="hsa:7535")

# For compounds, use UniChem
from bioservices import UniChem
u = UniChem()
chembl_from_kegg = u.get_compound_id_from_kegg("C11222")

Supported mappings (UniProt):

  • UniProtKB ↔ KEGG
  • UniProtKB ↔ Ensembl
  • UniProtKB ↔ PDB
  • UniProtKB ↔ RefSeq
  • And many more (see references/identifier_mapping.md)

6. Gene Ontology Queries

Access GO terms and annotations:

from bioservices import QuickGO

g = QuickGO(verbose=False)

# Retrieve GO term information
term_info = g.Term("GO:0003824", frmt="obo")

# Search annotations
annotations = g.Annotation(protein="P43403", format="tsv")

7. Protein-Protein Interactions

Query interaction databases via PSICQUIC. PSICQUIC is not shipped by every release — it is absent from 1.16.0 — so import it defensively and fall back to IntactComplex, OmniPath, or STRING when it is missing:

from bioservices import PSICQUIC

s = PSICQUIC(verbose=False)

# Query specific database (e.g., MINT)
interactions = s.query("mint", "ZAP70 AND species:9606")

# List available interaction databases
databases = s.activeDBs

Available databases: MINT, IntAct, BioGRID, DIP, and 30+ others.

Multi-Service Integration Workflows

BioServices excels at combining multiple services for comprehensive analysis. Common integration patterns:

Complete Protein Analysis Pipeline

Execute a full protein characterization workflow:

export NCBI_EMAIL=your.email@example.com
python scripts/protein_analysis_workflow.py ZAP70_HUMAN
# Or pass email as optional second argument if NCBI_EMAIL is unset
python scripts/protein_analysis_workflow.py ZAP70_HUMAN your.email@example.com

This script demonstrates:

  1. UniProt search for protein entry
  2. FASTA sequence retrieval
  3. BLAST similarity search
  4. KEGG pathway discovery
  5. PSICQUIC interaction mapping

Pathway Network Analysis

Analyze all pathways for an organism:

python scripts/pathway_analysis.py hsa output_directory/

Extracts and analyzes:

  • All pathway IDs for organism
  • Protein-protein interactions per pathway
  • Interaction type distributions
  • Exports to CSV/SIF formats

Cross-Database Compound Search

Map compound identifiers across databases:

python scripts/compound_cross_reference.py Geldanamycin

Retrieves:

  • KEGG compound ID
  • ChEBI identifier
  • ChEMBL identifier
  • Basic compound properties

Batch Identifier Conversion

Convert multiple identifiers at once:

python scripts/batch_id_converter.py input_ids.txt --from UniProtKB_AC-ID --to KEGG

Best Practices

Output Format Handling

Different services return data in various formats:

  • XML: Parse using BeautifulSoup (most SOAP services)
  • Tab-separated (TSV): Pandas DataFrames for tabular data
  • Dictionary/JSON: Direct Python manipulation
  • FASTA: BioPython integration for sequence analysis

Rate Limiting and Verbosity

Control API request behavior:

from bioservices import KEGG

k = KEGG(verbose=False)  # Suppress HTTP request details
k.TIMEOUT = 30  # Adjust timeout for slow connections

Error Handling

Wrap service calls in try-except blocks:

try:
    results = u.search("ambiguous_query")
    if results:
        # Process results
        pass
except Exception as e:
    print(f"Search failed: {e}")

Organism Codes

Use standard organism abbreviations:

  • hsa: Homo sapiens (human)
  • mmu: Mus musculus (mouse)
  • dme: Drosophila melanogaster
  • sce: Saccharomyces cerevisiae (yeast)

List all organisms: k.list("organism") or k.organismIds

Integration with Other Tools

BioServices works well with:

  • BioPython: Sequence analysis on retrieved FASTA data
  • Pandas: Tabular data manipulation
  • PyMOL: 3D structure visualization (retrieve PDB IDs)
  • NetworkX: Network analysis of pathway interactions
  • Galaxy: Custom tool wrappers for workflow platforms

Resources

scripts/

Executable Python scripts demonstrating complete workflows:

  • protein_analysis_workflow.py: End-to-end protein characterization
  • pathway_analysis.py: KEGG pathway discovery and network extraction
  • compound_cross_reference.py: Multi-database compound searching
  • batch_id_converter.py: Bulk identifier mapping utility

Scripts can be executed directly or adapted for specific use cases.

references/

Detailed documentation loaded as needed:

  • services_reference.md: Comprehensive list of all 40+ services with methods
  • workflow_patterns.md: Detailed multi-step analysis workflows
  • identifier_mapping.md: Complete guide to cross-database ID conversion

Load references when working with specific services or complex integration tasks.

Installation

uv pip install "bioservices==1.16.0"

Dependencies are installed automatically. Upstream CI tests Python 3.9–3.12 (PyPI, docs).

Credentials

Most services need no API key. Exceptions:

Service Requirement
NCBI BLAST Contact email via NCBI_EMAIL or email= in NCBIblast.run()
Some EBI services Optional; check service docs if rate-limited

Set once per shell session:

export NCBI_EMAIL=your.email@example.com

Use a real institutional or lab address — NCBI may contact you about heavy BLAST usage.

Additional Information

For detailed API documentation and advanced features, refer to:

Related skills

  • gget: Queries 20+ bioinformatics databases and analysis services through the gget CLI and Python package, covering Ensembl gene search, info and…
  • biopython: Provides Biopython (Bio.Seq, Bio.SeqIO, Bio.Align, Bio.Entrez, Bio.Blast, Bio.PDB, Bio.Phylo, Bio.motifs, Bio.SeqUtils, Bio.Restriction) fo…
  • pathway-enrichment: Run pathway and gene-set enrichment analysis on gene lists or ranked gene data, then interpret the results.

Trigger Prompts & Evaluation Corpus

These evaluation prompts test that the agent correctly selects bioservices for relevant tasks and leaves it out for near misses.

Should trigger (3)

  • should trigger

    “How do I map a list of UniProt accessions to KEGG gene IDs with bioservices?”

    expects Uses bioservices.UniProt().mapping(fr='UniProtKB_AC-ID', to='KEGG', query=...) with a comma-separated or batched list. Parses the returned dictionary and handles unmapped IDs.

  • should trigger

    “I have a CSV called hits.csv with a column of human UniProt IDs (P04637, P38398, Q00987, etc.). For each one I need the KEGG pathways it belongs to, the Reactome pathway names, and any ChEMBL target ID. My script crashed with 'AttributeError: module bioservices has no attribute PSICQUIC' when I tried to add interactions too. Can you write the pipeline?”

    expects Writes a script that uses UniProt mapping to KEGG and ChEMBL, then KEGG get_pathway_by_gene and Reactome lookups, merged with pandas. Explains that PSICQUIC is absent from bioservices 1.16.0 and imports it defensively, falling back to IntactComplex, OmniPath or STRING. Uses error handling and sensible rate/verbosity settings.

  • should trigger

    “I'm studying imatinib and want one table that links its KEGG compound entry to the ChEBI and ChEMBL identifiers, plus whatever protein targets are listed, all pulled programmatically from the public databases. How should I go about it in Python?”

    expects Proposes bioservices: KEGG search for the compound, UniChem for KEGG-to-ChEMBL/ChEBI mapping, and ChEMBL get_molecule. Notes that the get_compound_id_from_* helpers are gone in 1.16.0 and checks hasattr or uses u.get_compounds(...) and reads res['compounds'][0]['sources']. Does not use pre-1.6 ChEMBL method names.

Near misses (2)

  • near miss

    “Quickly get the Ensembl gene ID, description and canonical transcript sequence for human TP53 using the gget command line.”

    expects Recommends gget (gget search, gget info, gget seq) for a quick single-database Ensembl lookup. Does not use bioservices.

  • near miss

    “I have a multi-record GenBank file, plasmids.gb. Parse it with SeqIO, pull out every CDS translation, and write them to a FASTA file.”

    expects Uses Bio.SeqIO to parse the GenBank records, iterates over CDS features to extract translations, and writes FASTA. This is local file manipulation, not a multi-database web query.