{"slug":"alterlab-bioservices","title":"alterlab-bioservices","summary":"Query 40+ bioinformatics web services through one consistent Python API with bioservices (UniProt, KEGG, ChEMBL, Reactome, Ensembl, NCBI and more). Use when a workflow must hit multiple databases together, map identifiers across services, or run cross-database analyses — for quic","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-09-23T18:56:53.21355Z","repo":{"url":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","stars":68,"forks":13,"license":"MIT","updatedAt":"2026-09-23T13:42:59Z"},"bodyHtml":"
\n

name: alterlab-bioservices\ndescription: Query 40+ bioinformatics web services through one consistent Python API with bioservices (UniProt, KEGG, ChEMBL, Reactome, Ensembl, NCBI and more). Use when a workflow must hit multiple databases together, map identifiers across services, or run cross-database analyses — for quick single-database lookups use gget, for sequence and file manipulation use biopython. Part of the AlterLab Academic Skills suite.\nlicense: GPL-3.0\nallowed-tools: Read Write Edit Bash(python:) Bash(uv:)\ncompatibility: \"Self-contained — runs under uv run python with bioservices installed (1.16.0 as of 2026-09, Python 3.9–3.14); no API key or account required, though several wrapped services want a contact email.\"\nmetadata:\nskill-author: AlterLab\nversion: \"1.1.0\"\nlast_updated: \"2026-09-23\"

\n

BioServices

\n

Overview

\n

BioServices is a Python package providing programmatic access to roughly 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.

\n

Recent changes that break old scripts (verified against bioservices 1.16.0):

\n\n

When to Use This Skill

\n

This skill should be used when:

\n\n

Does NOT Trigger

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ScenarioUse Instead
A single quick lookup (one gene, one structure, one enrichment)alterlab-gget
Parsing sequence/structure files or scripting Entrez directlyalterlab-biopython
Local BLAST+ / makeblastdb / DIAMOND on your own databasealterlab-blast
Deep work in one database (full KEGG, UniProt, or ChEMBL feature set)alterlab-kegg, alterlab-uniprot, alterlab-chembl
Cheminformatics on the retrieved structures (descriptors, fingerprints)alterlab-rdkit
\n

Core Capabilities

\n

1. Protein Analysis

\n

Retrieve protein information, sequences, and functional annotations:

\n
from bioservices import UniProt\n\nu = UniProt(verbose=False)\n\n# Search for protein by name. frmt is one of xlsx/fasta/json/gff/tsv — \"tab\" was\n# retired with the June-2022 UniProt API and now raises.\nresults = u.search(\"ZAP70_HUMAN\", frmt=\"tsv\", columns=\"accession,gene_names,organism_name\")\n\n# Retrieve FASTA sequence (frmt defaults to json)\nsequence = u.retrieve(\"P43403\", frmt=\"fasta\")\n\n# Map identifiers between databases -> {\"results\": [{\"from\": ..., \"to\": ...}], \"failedIds\": [...]}\njob = u.mapping(fr=\"UniProtKB_AC-ID\", to=\"KEGG\", query=\"P43403\")\nkegg_ids = [r[\"to\"] for r in job[\"results\"]]\n
\n

Key methods:

\n\n

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

\n

2. Pathway Discovery and Analysis

\n

Access KEGG pathway information for genes and organisms:

\n
from bioservices import KEGG\n\nk = KEGG()\nk.organism = \"hsa\"  # Set to human\n\n# Search for organisms\nk.lookfor_organism(\"droso\")  # Find Drosophila species\n\n# Find pathways by name\nk.lookfor_pathway(\"B cell\")  # Returns matching pathway IDs\n\n# Get pathways containing specific genes\npathways = k.get_pathway_by_gene(\"7535\", \"hsa\")  # ZAP70 gene\n\n# Retrieve and parse pathway data\ndata = k.get(\"hsa04660\")\nparsed = k.parse(data)\n\n# Extract pathway interactions\ninteractions = k.parse_kgml_pathway(\"hsa04660\")\nrelations = interactions['relations']  # Protein-protein interactions\n\n# Convert to Simple Interaction Format\nsif_data = k.pathway2sif(\"hsa04660\")\n
\n

Key methods:

\n\n

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

\n

3. Compound Database Searches

\n

Search and cross-reference compounds across multiple databases:

\n
from bioservices import KEGG\n\nk = KEGG()\n\n# Search compounds by name — the tab-separated result rows are \"C11222\\tGeldanamycin\"\nresults = k.find(\"compound\", \"Geldanamycin\")\n\n# Get compound information with database links\ncompound_info = k.get(\"cpd:C11222\")  # Includes ChEBI links\n\n# Cross-reference KEGG compound → ChEBI (KEGG→ChEMBL has no direct API)\nmapping = k.conv(\"chebi\", \"compound\")\nmapping[\"cpd:C11222\"]   # -> 'chebi:5292'  (Geldanamycin)\n
\n

Common workflow:

\n
    \n
  1. Search compound by name in KEGG
    2. \n
  2. Extract KEGG compound ID
    3. \n
  3. Use KEGG.conv for KEGG → ChEBI mapping (ChEBI IDs are also embedded in KEGG entries)
    4. \n
  4. If a ChEMBL ID is required, obtain it via a separate route (the ChEMBL web service / chembl_webresource_client, or the live UniChem REST API directly) — there is no bioservices UniChem convenience method for KEGG → ChEMBL
    5. \n
\n

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

\n

4. Sequence Analysis

\n

Run BLAST searches and sequence alignments:

\n
from bioservices import NCBIblast\n\ns = NCBIblast(verbose=False)\n\n# Run BLASTP against UniProtKB via the EBI job service\njobid = s.run(\n    program=\"blastp\",\n    sequence=protein_sequence,\n    stype=\"protein\",\n    database=\"uniprotkb\",\n    email=\"your.email@example.com\"  # a real address is required; jobs are killed without one\n)\n\n# Poll, then fetch. Method names are snake_case since the API refresh.\ns.wait(jobid)                    # blocks until the job leaves RUNNING\nstatus = s.get_status(jobid)     # RUNNING | FINISHED | ERROR | FAILURE | NOT_FOUND\nresults = s.get_result(jobid, \"out\")\nprint(s.get_result_types(jobid))  # what formats this job can return\n
\n

BLAST jobs are asynchronous — check the status (or call wait) before retrieving results.\nFor jobs submitted to NCBI rather than EBI, bioservices 1.16 adds\nfrom bioservices import NCBIBlastAPI with the same run/get_status/get_result shape.

\n

5. Identifier Mapping

\n

Convert identifiers between different biological databases:

\n
from bioservices import UniProt, KEGG\n\n# UniProt mapping (many database pairs supported)\nu = UniProt()\njob = u.mapping(\n    fr=\"UniProtKB_AC-ID\",  # Source database\n    to=\"KEGG\",              # Target database\n    query=\"P43403\"          # Identifier(s) to convert; a list is also accepted\n)\n\n# The payload is {\"results\": [{\"from\": ..., \"to\": ...}], \"failedIds\": [...]}.\n# Collapse it yourself when you want a per-source-ID dict:\nfrom collections import defaultdict\n\nmapped = defaultdict(list)\nfor row in job[\"results\"]:\n    mapped[row[\"from\"]].append(row[\"to\"])\n\n# KEGG gene ID -> UniProt. Non-UniProt sources may only map *to* UniProtKB,\n# so \"KEGG\" -> \"UniProtKB\" is valid while \"KEGG\" -> \"UniProtKB_AC-ID\" is not.\nkegg_to_uniprot = u.mapping(fr=\"KEGG\", to=\"UniProtKB\", query=\"hsa:7535\")\n\n# For compounds, map KEGG → ChEBI via KEGG.conv\n# (KEGG → ChEMBL has no direct API; obtain ChEMBL IDs separately\n#  via the ChEMBL web service / chembl_webresource_client or the\n#  live UniChem REST API directly)\nk = KEGG()\nkegg_to_chebi = k.conv(\"chebi\", \"compound\")\nchebi_from_kegg = kegg_to_chebi[\"cpd:C11222\"]  # -> 'chebi:5292'\n
\n

Supported mappings (UniProt):

\n\n

6. Gene Ontology Queries

\n

Access GO terms and annotations:

\n
from bioservices import QuickGO\n\ng = QuickGO(verbose=False)\n\n# Retrieve GO term information (returns parsed JSON from the QuickGO REST API)\nterm_info = g.get_go_terms(\"GO:0003824\")\nancestors = g.get_go_ancestors(\"GO:0003824\")\n\n# Annotations: the parameters follow the QuickGO REST API, not the old\n# protein=/format= signature. geneProductId is prefixed, limit is capped at 100.\nannotations = g.Annotation(\n    geneProductId=\"UniProtKB:P43403\",\n    includeFields=\"goName\",\n    limit=100,\n    page=1,\n)\nfor row in annotations[\"results\"][:5]:\n    print(row[\"goId\"], row[\"goName\"], row[\"goAspect\"])\n
\n

Annotation returns a dict with numberOfHits and results; page through it rather than\nraising limit (values above 100 raise a TypeError).

\n

7. Protein-Protein Interactions

\n

PSICQUIC and BioGRID were removed from bioservices in 1.14. Use the STRING service (or\nIntactComplex for curated complexes):

\n
from bioservices import STRING\n\ns = STRING()\n\n# Functional + physical partners of a protein\npartners = s.get_interaction_partners(\"ZAP70\", species=9606, limit=20)\n\n# Interactions within a given set of proteins\nnetwork = s.get_interactions([\"ZAP70\", \"CD247\", \"LCK\"], species=9606)\n\nfor row in partners:\n    print(row[\"preferredName_A\"], row[\"preferredName_B\"], row[\"score\"])\n
\n

network_type=\"physical\" restricts to physical complexes; required_score (0–1000) sets\nthe confidence floor. STRING scores are 0–1 in the JSON output.

\n

Multi-Service Integration Workflows

\n

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

\n

Complete Protein Analysis Pipeline

\n

Execute a full protein characterization workflow:

\n
python scripts/protein_analysis_workflow.py ZAP70_HUMAN your.email@example.com\n
\n

This script demonstrates:

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

Pathway Network Analysis

\n

Analyze all pathways for an organism:

\n
python scripts/pathway_analysis.py hsa output_directory/\n
\n

Extracts and analyzes:

\n\n

Cross-Database Compound Search

\n

Map compound identifiers across databases:

\n
python scripts/compound_cross_reference.py Geldanamycin\n
\n

Retrieves:

\n\n

Batch Identifier Conversion

\n

Convert multiple identifiers at once:

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

Best Practices

\n

Output Format Handling

\n

Different services return data in various formats:

\n\n

Rate Limiting and Verbosity

\n

Control API request behavior:

\n
from bioservices import KEGG\n\nk = KEGG(verbose=False)  # Suppress HTTP request details\nk.TIMEOUT = 30  # Adjust timeout for slow connections\n
\n

Error Handling

\n

Wrap service calls in try-except blocks:

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

Organism Codes

\n

Use standard organism abbreviations:

\n\n

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

\n

Integration with Other Tools

\n

BioServices works well with:

\n\n

Resources

\n

scripts/

\n

Executable Python scripts demonstrating complete workflows:

\n\n

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

\n

references/

\n

Detailed documentation loaded as needed:

\n\n

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

\n

Installation

\n
uv pip install bioservices\n
\n

Dependencies are automatically managed. Package is tested on Python 3.9-3.12.

\n

Additional Information

\n

For detailed API documentation and advanced features, refer to:

\n\n

Part of the AlterLab Academic Skills suite.

\n","files":[{"path":"evals/evals.json","sizeBytes":4288,"isText":true},{"path":"references/identifier_mapping.md","sizeBytes":19506,"isText":true},{"path":"references/services_reference.md","sizeBytes":17842,"isText":true},{"path":"references/workflow_patterns.md","sizeBytes":20300,"isText":true},{"path":"scripts/batch_id_converter.py","sizeBytes":11954,"isText":true},{"path":"scripts/compound_cross_reference.py","sizeBytes":10344,"isText":true},{"path":"scripts/pathway_analysis.py","sizeBytes":9557,"isText":true},{"path":"scripts/protein_analysis_workflow.py","sizeBytes":13223,"isText":true},{"path":"SKILL.md","sizeBytes":14432,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-23T18:57:12.983894Z","sha256":"5E2D67B4D1B88C9F93668B1E74EB18503ED74EDFCB9C0019E71B84F85C38ADF4","sizeBytes":42395},"review":null,"source":{"repositoryUrl":"https://github.com/AlterLab-IEU/AlterLab-Academic-Skills","path":"skills/bioinformatics/alterlab-bioservices","license":"MIT","commit":"e4836c08a20da195a11f30f203a8cf23ec30aa95","subtreeSha":"C361C111F68441F97D6BCE4D7790EE7D3C4A8ABCF8637BF586682BE091C51332","lastSyncedAt":"2026-09-23T18:56:52.297238Z"},"reviewedAt":"2026-09-23T18:57:50.253185Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/AlterLab-IEU/AlterLab-Academic-Skills/tree/main/skills/bioinformatics/alterlab-bioservices"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install alterlab-ieu-alterlab-academic-skills@llmmart"},{"target":"git","command":"git clone https://github.com/AlterLab-IEU/AlterLab-Academic-Skills.git"}]}