BioServices service contracts

Reviewed 2026-09-30 against bioservices 1.16.0, the official SDK reference, its linked source, and representative unauthenticated provider reads. These are service-specific contracts, not a promise that all providers are always available. JSON field names below refer to the response, not to a uniform BioServices model.

Core clients

UniProt

Base: https://rest.uniprot.org. search(query, frmt="tsv", columns=None, limit=None, size=25, ...) calls GET /uniprotkb/search; columns becomes fields. Current fields include accession,id,gene_names,organism_name,length, protein_name,go_id,xref_pdb. Search supports TSV/JSON/FASTA/GFF/XLSX, not tab, XML or plain text. Use organism_id:9606 in queries. The removed searchUniProtId helper is not available.

retrieve(accession, frmt="json") calls the legacy /uniprot/{id}.{format} route, which was verified redirecting to /uniprotkb/{id}.{format}. JSON gives one entry dictionary (primaryAccession, organism.taxonId); FASTA/TXT/XML return text. retrieve(..., frmt="tab") is invalid.

mapping(fr, to, query, polling_interval_seconds=3, max_waiting_time=100, progress=True) submits form fields from, to, ids to POST /idmapping/run, polls /idmapping/status/{jobId}, follows results pagination, and returns {"results": [{"from": ..., "to": ...}], "failedIds": [...]}. Timeout may return None; a target may be a record rather than an ID. See identifier mapping. valid_mapping retrieves GET /configure/idmapping/fields; use it to check a pair before submission.

The SDK's search pagination mixes limit and size and removes its sort parameter before transmission. For small bounded lookups use size=limit<=500. For a full search use limit=None with a supported page size and verify counts; do not describe a bounded result as exhaustive or assume SDK sort is applied.

Sources: SDK source, live mapping configuration.

KEGG

Set k.services.url = "https://rest.kegg.jp" because 1.16.0 initializes HTTP. list(database, organism=None) calls /list/{database}[/{organism}]; find(database, query, option=None) calls /find/{database}/{query}[/{option}]. Both return TSV strings. At review /list/organism returned HTTP 400 despite being documented. This breaks organism assignment and find/conv/link validation in 1.16.0. Prefer scoped requests through k.services.http_get when this catalogue is unavailable; the bundled scripts demonstrate that workaround. get(entries, option=None, parse=False) calls /get/{entries}[/{option}]; default output is flat-file text. parse returns a dictionary. lookfor_organism/lookfor_pathway filter the downloaded lists; get_pathway_by_gene(gene, organism) parses the gene's PATHWAY section into an ID-to-name dictionary (or None), not a list.

conv(target, source) and link(target, source) call the respective REST operations; the wrapper reduces them to a dictionary and can overwrite repeated source rows. Preserve raw TSV when one-to-many relationships matter. parse_kgml_pathway(id) retrieves /get/{id}/kgml and returns entries and relations. A relation subtype is a separate row (entry1, entry2, link, name, value); subtype-less relations have name=None. Nodes have id, name, type, gene_names, and link. Local numeric node IDs are not gene IDs.

pathway2sif(id, uniprot=False) returns lists [source, 1 or -1, target] for PPrel activation/inhibition between gene entries. It discards other relation classes and group nodes. The default UniProt conversion selects the first gene from multi-gene entries; use the explicit False form and review multiplicity.

Use <=3 requests/sec. get allows ten flat-file entries per call and one KGML pathway. API access is limited to academic use; consult provider licensing for other use. Sources: REST manual, access rules, KGML.

QuickGO

Base: https://www.ebi.ac.uk/QuickGO/services. get_go_terms("GO:0003824") calls /ontology/go/terms/{ids} and extracts the results list. go_search(query, limit=600, page=1) calls /ontology/go/search and also extracts a list, losing pagination metadata. Annotation(geneProductId="UniProtKB:P43403", includeFields="goName", limit=100, page=1, ...) calls /annotation/search and returns the full JSON object with numberOfHits, results, and pageInfo. Increment page through pageInfo.total; the SDK limits annotation page size to 100.

Annotation rows use goId, goName, goAspect (full names such as biological_process), qualifier, evidenceCode, reference, and taxonId. There is no Term method or protein, format argument to Annotation. Do not reuse the stale SDK docstring's limit=-1 advice: its code rejects it. Provider API, SDK source.

ChEBI, ChEMBL, and UniChem

Sources: ChEBI API, ChEMBL API, UniChem API, SDK chemical clients.

BLAST and interaction resources

NCBIblast is the EMBL-EBI hosted NCBI BLAST program. Set services.url="https://www.ebi.ac.uk/Tools/services/rest/ncbiblast". get_parameters() and get_parameter_details(name) query /parameters and /parameterdetails/{name}; discover supported programs/databases. run(...) submits form data to /run (program, sequence, email, stype, database) and returns a job-ID string. get_status reads /status/{id}; get_result_types reads /resulttypes/{id}; get_result(id, kind) reads /result/{id}/{kind}. The SDK supports out/error/sequence/ids/xml retrieval types; check advertised result types before choosing. Completed status is FINISHED; FAILURE, ERROR, and NOT_FOUND terminate a bounded wait. getStatus and getResult are absent. No live job was submitted. Job Dispatcher guide.

PSICQUIC is not exported by 1.16.0; no executable legacy PSICQUIC example is supported here. These alternatives answer different scientific questions:

• STRING.get_interaction_partners(ids, species=taxon_id, required_score=700, limit=10) -> https://string-db.org/api/json/interaction_partners; list of edges with stable STRING IDs, names, combined and evidence-channel scores. required_score uses 0–1000; JSON scores use 0–1. Functional associations need not imply physical binding. Pin a versioned host for reproducible production use; this SDK builds URLs from STRING._url, not services.url, and bypasses transport timeout/rate controls. STRING API.
• IntactComplex.search(query, first=0, number=10) -> https://www.ebi.ac.uk/intact/complex-ws/search/{query}; JSON elements, totalNumberOfResults. details(complex_ac) uses /details/{accession}. Set its services.url to HTTPS. Complex membership is not pairwise evidence.
• OmniPath.get_interactions(query)/get_ptms(query) exist, but the 1.16.0 path-style filter is unsafe: /interactions/P43403 returned the full dataset in review. Use documented query parameters through its transport instead:

from bioservices import OmniPath
op = OmniPath(verbose=False)
op.services.url = "https://omnipathdb.org"
rows = op.services.http_get("interactions", frmt="json", params={
    "partners": "P43403", "format": "json", "fields": "sources,references",
})
assert isinstance(rows, list)
assert all(row["source"] == "P43403" or row["target"] == "P43403" for row in rows)

For enzyme/substrate modifications use the /enzsub endpoint described in OmniPath's webservice guide, not the legacy /ptms/{query} route. Check evidence sources and direction separately.

Additional documented clients

These signatures were checked in the SDK; representative reads were verified where indicated. Examples not exercised end-to-end remain illustrative.

References for these clients: SDK methods and linked implementation, HGNC REST, MyGene API, PubChem PUG REST, Reactome Content Service, BioStudies API, RCSB Search API, InterPro API, Pfam transition.

Transport behavior

For composed wrappers use client.services.TIMEOUT, client.services.url, and client.services.requests_per_sec; direct REST subclasses such as ChEBI expose those properties directly. cache=True is a constructor option where supported; the transport property is CACHING, not CACHE. No universal DELAY attribute exists. Inspect type and shape before treating a truthy integer HTTP status as valid data; HTML at status 200 is also not a successful scientific response.