bioservices

BioServices - Unified Query Interface for Bioinformatics Databases

Overview

BioServices is a Python package that provides a unified interface for accessing more than 40 bioinformatics web services and databases, including UniProt, KEGG, ChEMBL, and PDB. It is suitable for scenarios that require querying multiple databases within a single workflow, performing cross-database analyses, and mapping identifiers. It supports Python 3.9–3.12 and is licensed under GPLv3.

Use Cases

1. Cross-Database Bioinformatics Analysis

When data needs to be integrated from multiple biological databases, BioServices provides a consistent API, eliminating the need to learn different query methods for each database. Typical use cases include retrieving protein sequences from UniProt, finding related metabolic pathways through KEGG, searching for compound information in ChEMBL, and finally integrating the results for analysis.

2. Biological Database Identifier Mapping

Convert identifiers between different databases, such as UniProtKB ↔ KEGG, UniProtKB ↔ Ensembl, and compound KEGG IDs ↔ ChEMBL. Batch conversion is supported, making BioServices suitable for analytical workflows that integrate multiple data sources.

3. Protein and Pathway Analysis

Core Features

1. Unified Database Access Interface

Supports more than 40 bioinformatics databases, including:

All services use a consistent calling pattern and support REST and SOAP/WSDL protocols.

2. Cross-Database Identifier Conversion

Provides convenient identifier mapping functionality:

from bioservices import UniProt
u = UniProt()
# UniProt → KEGG
results = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")

Conversions between multiple database pairs are supported, eliminating the need to look up mapping relationships manually.

3. Comprehensive Workflow Support

Complete workflow script examples are provided, covering common scenarios such as protein analysis, pathway analysis, and compound searches.

Frequently Asked Questions

Which biological databases does BioServices support?

BioServices supports approximately 40 bioinformatics databases, including:

See the references/services_reference.md document for the complete list.

How can I use BioServices to query UniProt protein information?

Basic query examples:

from bioservices import UniProt
u = UniProt(verbose=False)

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

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

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

For more detailed usage, see the “Core Capabilities” section of the skill documentation.

Should I choose BioServices or Biopython?

These two tools are complementary rather than alternatives:

They are recommended for use together: use BioServices to retrieve data from databases, and Biopython to process and analyze sequences locally.

Other comparisons:

Does BioServices require API keys?

Most services do not require API keys. Exceptions include:

Set the email address as follows:

export NCBI_EMAIL=your.email@example.com

How can I batch-convert biological database identifiers?

BioServices supports batch conversion, allowing multiple identifiers to be converted at once:

from bioservices import UniProt
u = UniProt()

# Batch UniProt → KEGG conversion
results = u.mapping(
    fr="UniProtKB_AC-ID",
    to="KEGG",
    query="P43403,P12345,P67890"  # Separate multiple IDs with commas
)

For large-scale batch processing, you can use the provided script:

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

Which Python versions does BioServices support?

It supports Python 3.9–3.12. Installing a pinned version is recommended:

uv pip install "bioservices==1.16.0"

The upstream CI tests cover Python 3.9–3.12 (as of March 2026).

How can I perform a BLAST search with BioServices?

import os
from bioservices import NCBIblast

s = NCBIblast(verbose=False)
email = os.environ["NCBI_EMAIL"]

# Submit a BLAST job
jobid = s.run(
    program="blastp",
    sequence=protein_sequence,
    stype="protein",
    database="uniprotkb",
    email=email,
)

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

Note: BLAST is an asynchronous task. You must first check that the job has completed before retrieving the results. The NCBI_EMAIL environment variable must be set.