Overview

This page describes our REST web services which are designed to provide computational access to the data in the Guide to PHARMACOLOGY. The web services currently serve up JSON files, though we will look at extending the range of options in the future. You can retrieve families, targets, genes, ligands, interactions and text annotations.

The GtoPdb web service base URL (base_url) is https://www.guidetopharmacology.org/services/ and points to the current version of the web services API. The API will be updated in accordance with normal database release cycles to accommodate new data types as required.

Specific services may be accessed by appending the correct portion of the URL as given below in the tables. Optional parameters can be included by appending a question mark (?) to the end of the service name and separating parameters with ampersand (&), e.g. https://www.guidetopharmacology.org/services/targets/290/interactions?affinityType=pKi&species=Human. Users can read a description of the web services output in the GtoPdb Web Service Output Description file

The Guide to PHARMACOLOGY database is licensed under the Open Data Commons Open Database License (ODbL) and its contents are licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

Further information may be obtained by emailing us. We are particularly keen to hear from people using the web services and have feedback.

Version 2.0

The second version of our web services was released on 23rd March 2017 and contains new interaction web services, returning lists of target-ligand pairs which can be filtered by target/ligand type, affinity etc., and reference web services, which can retrieve references by id or the full interaction reference set. There are some minor changes to the way that specific target and ligand interactions are accessed too, with new filtering options and simplification of the results so that just a single list of interactions is returned rather than grouping the same types of interaction together. We have also made improvements to the speed of accessing many of the web services (though it should be noted that retrieving a large list of several thousand results does take more than a few seconds). We have also introduced a basic anonymous tracking mechanism to count the number of hits so that we can better monitor usage and inform future development (this does not record any information about the client).

Python wrapper

pyGtoP provides a Python interface to the web services, which is available on GitHub. Full documentation is available here. The Python wrapper was created as part of another project and is not actively maintained, however please email us with any questions or bug reports and we'll do our best to help.

Target web services

ServiceURLParameters
List of targets{base_url}/targets
type (optional): The target class abbreviation, i.e. 'GPCR', 'NHR', 'LGIC', 'VGIC', 'OtherIC', 'Enzyme', 'CatalyticReceptor', 'Transporter', 'OtherProtein', 'AccessoryProtein'
name (optional): search for targets by name
geneSymbol (optional): a human, mouse or rat gene symbol
ecNumber (optional): an Enzyme Commission (EC) number
accession (optional): an external database accession number or Id
database (optional): the name* of the database the accession number relates to (default = UniProt)
immuno (optional): filter targets based on whether they are tagged in GtoImmuPdb (true or false)
malaria (optional): filter ligands based on whether they are tagged in GtoMPdb (true or false)
Single target{base_url}/targets/{targetId}
targetId: a GtoPdb target Id
List of target families{base_url}/targets/families
type (optional): target class abbreviation as above
name (optional): search for families by name
Single family{base_url}/targets/families/{familyId}
familyId: a GtoPdb family Id
Component subunits{base_url}/targets/{targetId}/subunits
Complexes{base_url}/targets/{targetId}/complexes
Synonyms{base_url}/targets/{targetId}/synonyms
Gene and protein information{base_url}/targets/{targetId}/geneProteinInformation
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Database links{base_url}/targets/{targetId}/databaseLinks
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
database (optional): the name* of the database to retrieve links for
Natural/endogenous ligands{base_url}/targets/{targetId}/naturalLigands
Interactions{base_url}/targets/{targetId}/interactions
type (optional): the type of ligand action, i.e. 'Activator', 'Agonist', 'Allosteric modulator', 'Antagonist', 'Antibody', 'Channel blocker', 'Gating inhibitor', 'Inhibitor', 'Subunit-specific'
affinityParameter (optional): one of 'pA2', 'pEC50', 'pIC50', 'pKB', 'pKd', 'pKi'
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
affinity (optional): returned results must have affinity greater than this value, e.g. 7.5.
ligandType (optional): the class of ligand, one of 'Synthetic organic', 'Metabolite', 'Natural product', 'Endogenous peptide', 'Peptide', 'Antibody', 'Inorganic', 'Labelled', 'INN'
approved (optional): boolean which indicates if the interactions are for approved drugs only
primaryTarget (optional): boolean which indicates whether results should only include interactions where the target is marked as the primary target
Rank order lists of ligands and other activators{base_url}/targets/{targetId}/rankOrder
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
These lists can contain details of substrates, endogenous ligands and other non-chemical activators (pH, heat etc.). The description field describes the list and the property field lists the ligands
Function{base_url}/targets/{targetId}/function
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Tissue distribution{base_url}/targets/{targetId}/tissueDistribution
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Functional assay{base_url}/targets/{targetId}/functionalAssay
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Gene expression and pathophysiology{base_url}/targets/{targetId}/geneExpressionPathophysiology
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Physiological consequences of altering gene expression{base_url}/targets/{targetId}/alteredExpression
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Xenobiotics influencing gene expression{base_url}/targets/{targetId}/xenobioticsGeneExpression
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Clinically-relevant mutations and pathophysiology{base_url}/targets/{targetId}/pathophysiology
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Diseases{base_url}/targets/{targetId}/diseases
Variants{base_url}/targets/{targetId}/variants
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
PDB structures{base_url}/targets/{targetId}/pdbStructure
Associated proteins{base_url}/targets/{targetId}/associatedProteins
Ion selectivity{base_url}/targets/{targetId}/ionSelectivity
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Ion conductance{base_url}/targets/{targetId}/ionConductance
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Ion channel voltage dependence{base_url}/targets/{targetId}/voltageDependence
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
GPCR transduction mechanisms{base_url}/targets/{targetId}/transduction
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
NHR binding partners{base_url}/targets/{targetId}/bindingPartners
NHR co-regulators{base_url}/targets/{targetId}/coregulators
NHR target genes{base_url}/targets/{targetId}/targetGenes
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
NHR DNA binding sequence{base_url}/targets/{targetId}/dnaBinding
Enzyme reaction{base_url}/targets/{targetId}/reactions
Substrates{base_url}/targets/{targetId}/substrates
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Products{base_url}/targets/{targetId}/products
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Cofactors{base_url}/targets/{targetId}/cofactors
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Target comments{base_url}/targets/{targetId}/comments
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
database (optional): the name* of the database to retrieve links for
Immunological Processes{base_url}/targets/{targetId}/immunoProcesses
Immunological Celltypes{base_url}/targets/{targetId}/immunoCelltypes
Target contributing authors{base_url}/targets/{targetId}/contributors
Family contributing authors{base_url}/targets/families/{familyId}/contributors
Family NC-IUPHAR subcommittee{base_url}/targets/families/{familyId}/subcommittee
Family overview{base_url}/targets/families/{familyId}/overview
Family comments{base_url}/targets/families/{familyId}/comments
Family introduction{base_url}/targets/families/{familyId}/introduction
Introduction contributing authors{base_url}/targets/families/{familyId}/introduction/contributors

Ligand web services

ServiceURLParameters
List of ligands{base_url}/ligands
type (optional): The ligand type, one of 'Synthetic organic', 'Metabolite', 'Natural product', 'Endogenous peptide', 'Peptide', 'Antibody', 'Inorganic', 'Approved', 'Withdrawn', 'Labelled', 'INN'
name (optional): search for ligands by name
geneSymbol (optional): a human, mouse or rat gene symbol
accession (optional): an external database accession number or Id
database (optional): the name* of the database the accession number relates to (default = PubChemCID)
inchikey (optional): the ligand's InChIKey, or for backbone matches (other isomers) just provide the backbone part (the first 14 characters)
lipinskyGt & lipinskyLt (optional): lower and upper cut-offs for the number of Lipinsky's rules broken
logpGt & logpLt (optional): lower and upper cut-offs for the LogP
molWeightGt & molWeightLt (optional): lower and upper cut-offs for the molecular weight
hBondAcceptorsGt & hBondAcceptorsLt (optional): lower and upper cut-offs for the number of hydrogen bond acceptors
hBondDonorsGt & hBondDonorsLt (optional): lower and upper cut-offs for the number of hydrogen bond donors
rotatableBondsGt & rotatableBondsLt (optional): lower and upper cut-offs for the number of rotatable bonds
tpsaGt & tpsaLt (optional): lower and upper cut-offs for the topological polar surface area
immuno (optional): filter ligands based on whether they are tagged in GtoImmuPdb (true or false)
malaria (optional): filter ligands based on whether they are tagged in GtoMPdb (true or false)
antibacterial (optional): filter ligands based on whether they are tagged as antibacterial (true or false)
Exact match structure search{base_url}/ligands/exact
smiles: a SMILES string to search
Substructure search{base_url}/ligands/substructure
smiles: a SMILES string to search
lipinskyGt & lipinskyLt (optional): lower and upper cut-offs for the number of Lipinsky's rules broken
logpGt & logpLt (optional): lower and upper cut-offs for the LogP
molWeightGt & molWeightLt (optional): lower and upper cut-offs for the molecular weight
hBondAcceptorsGt & hBondAcceptorsLt (optional): lower and upper cut-offs for the number of hydrogen bond acceptors
hBondDonorsGt & hBondDonorsLt (optional): lower and upper cut-offs for the number of hydrogen bond donors
rotatableBondsGt & rotatableBondsLt (optional): lower and upper cut-offs for the number of rotatable bonds
tpsaGt & tpsaLt (optional): lower and upper cut-offs for the topological polar surface area

Structure similarity search
{base_url}/ligands/similarity
smiles: a SMILES string to search
similarityGt (optional): lower cut-off for the % similarity (use decimal, i.e. 80% = 0.8)
lipinskyGt & lipinskyLt (optional): lower and upper cut-offs for the number of Lipinsky's rules broken
logpGt & logpLt (optional): lower and upper cut-offs for the LogP
molWeightGt & molWeightLt (optional): lower and upper cut-offs for the molecular weight
hBondAcceptorsGt & hBondAcceptorsLt (optional): lower and upper cut-offs for the number of hydrogen bond acceptors
hBondDonorsGt & hBondDonorsLt (optional): lower and upper cut-offs for the number of hydrogen bond donors
rotatableBondsGt & rotatableBondsLt (optional): lower and upper cut-offs for the number of rotatable bonds
tpsaGt & tpsaLt (optional): lower and upper cut-offs for the topological polar surface area
List of ligand families/groups{base_url}/ligands/families
name (optional): search for families/groups by name
Single ligand{base_url}/ligands/{ligandId}
ligandId: a GtoPdb ligand Id
Path to image file{base_url}/ligands/{ligandId}/image
Ligand structure{base_url}/ligands/{ligandId}/structure
Component subunits{base_url}/ligands/{ligandId}/subunits
Complexes{base_url}/ligands/{ligandId}/complexes
Precursors (endogenous peptides){base_url}/ligands/{ligandId}/precursors
Molecular properties (non-peptides){base_url}/ligands/{ligandId}/molecularProperties
Synonyms{base_url}/ligands/{ligandId}/synonyms
Database links{base_url}/ligands/{ligandId}/databaseLinks
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
database (optional): the name* of the database to retrieve links for
Interactions{base_url}/ligands/{ligandId}/interactions
type (optional): the type of interaction, i.e. 'Activator', 'Agonist', 'Allosteric modulator', 'Antagonist', 'Antibody', 'Channel blocker', 'Gating inhibitor', 'Inhibitor', 'Subunit-specific'
affinityParameter (optional): one of 'pA2', 'pEC50', 'pIC50', 'pKB', 'pKd', 'pKi'
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
affinity (optional): returned results must have affinity greater than this value, e.g. 7.5.
asTarget (optional): boolean which indicates if this ligand Id should be considered as the target of interactions by other ligands, e.g. antibodies (default = true)
asLigand (optional): boolean which indicates if this ligand Id should be considered as the ligand interacting with other targets (default = true)
targetType (optional): name of a target class, i.e. 'GPCR', 'NHR', 'LGIC', 'VGIC', 'OtherIC', 'Enzyme', 'CatalyticReceptor', 'Transporter', 'OtherProtein'
primaryTarget (optional): boolean which indicates whether results should only include interactions marked as primary targets
Rank order lists of ligands at targets{base_url}/ligands/{ligandId}/rankOrder
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Ligand comments and clinical use information{base_url}/ligands/{ligandId}/comments

Interaction web services

ServiceURLParameters
List of interactions{base_url}/interactions
type (optional): the type of ligand action, i.e. 'Activator', 'Agonist', 'Allosteric modulator', 'Antagonist', 'Antibody', 'Channel blocker', 'Gating inhibitor', 'Inhibitor', 'Subunit-specific'
affinityParameter (optional): one of 'pA2', 'pEC50', 'pIC50', 'pKB', 'pKd', 'pKi'
species (optional): the species common name, e.g. 'Human, 'Mouse', 'Rat' etc.
Plasmodium species (optional): the species short name, e.g. For P. falciparum use 'Pf'; for P. vivax use 'Pv'; for P. knowlesi use 'Pk'; for P. berghei use 'Pb'; for P. cynomolgi use 'Pc'; for P. yoelii use 'Py'
affinity (optional): returned results must have affinity greater than this value, e.g. 7.5.
ligandType (optional): the class of ligand, one of 'Synthetic organic', 'Metabolite', 'Natural product', 'Endogenous peptide', 'Peptide', 'Antibody', 'Inorganic', 'Labelled', 'INN'
approved (optional): boolean which indicates if the interactions are for approved drugs only
primaryTarget (optional): boolean which indicates if the targets should be marked as primary targets only
targetType (optional): name of a target class, i.e. 'GPCR', 'NHR', 'LGIC', 'VGIC', 'OtherIC', 'Enzyme', 'CatalyticReceptor', 'Transporter', 'OtherProtein'
structureSearchType (optional): perform ligand structure-based searching, one of 'similarity' (the default if SMILES are provided), 'substructure' or 'exact'
smiles (optional): a SMILES string to search
similarityGt (optional): lower cut-off for the % similarity (default = 0.85)
inchikey (optional): perform ligand structure search using an InChIKey, or for backbone matches (other isomers) just provide the backbone part (the first 14 characters)
Note: the results are formatted as target-ligand interaction pair summaries, which are linked to individual interactions.
Single interaction{base_url}/interactions/{interactionsId}
interactionId: a GtoPdb interaction Id

Disease web services

ServiceURLParameters
List of diseases{base_url}/diseases
name (optional): search for diseases by name
synonym (optional): search specifically with disease synonyms
database (optional): the name* of the database the accession number relates to (default = OMIM)
accession (optional): an external database accession ID or number Note, this should be used in conjuction with the database parameter.
Single disease{base_url}/diseases/{diseaseId}
diseaseId: a GtoPdb disease Id
Targets associated with disease{base_url}/diseases/{diseaseId}/diseaseTargets
diseaseId: a GtoPdb disease Id
Ligands associated with disease{base_url}/diseases/{diseaseId}/diseaseLigands
diseaseId: a GtoPdb disease Id
approved (optional): set to 'true' to restrict to just approved ligands. Note, omitting this option, or setting to false will return all ligands

Reference web services

ServiceURLParameters
List of references{base_url}/refs
filter (optional): a filter for the reference list, currently 'interactions' is supported which returns a list of all references associated with target-ligand interactions
Warning: the full reference list (>30,000 refs) is very slow to load.
Single reference{base_url}/refs/{referenceId}
referenceId: a GtoPdb reference Id

Examples

These are a few example use cases for the web services.

  1. Retrieve the target with Ensembl gene Id ENSG00000097007:
    https://www.guidetopharmacology.org/services/targets?accession=ENSG00000097007&database=EnsemblGene
  2. Retrieve the target encoded by HGNC gene symbol CATSPER4:
    https://www.guidetopharmacology.org/services/targets?geneSymbol=CATSPER4
  3. Search for the target with name HER3:
    https://www.guidetopharmacology.org/services/targets?name=HER3
  4. Find the subunits of 5-HT3AB (target Id 378):
    https://www.guidetopharmacology.org/services/targets/378/subunits
  5. Find agonists of GPER (target Id 221) with pKi >= 7:
    https://www.guidetopharmacology.org/services/targets/221/interactions?type=Agonist&affinityType=pKi&affinity=7
  6. Retrieve all the approved drugs:
    https://www.guidetopharmacology.org/services/ligands?type=Approved
  7. Find synonyms for tamoxifen (ligand Id 1016) :
    https://www.guidetopharmacology.org/services/ligands/1016/synonyms
  8. Find ligands at least 80% similar to the structure CC(CN(C)C)CN1c2ccccc2Sc2ccccc12:
    https://www.guidetopharmacology.org/services/ligands/similarity?smiles=CC(CN(C)C)CN1c2ccccc2Sc2ccccc12&similarityGt=0.8
  9. Find ligands with the substructure Nc1cnc(Cl)c(N)n1 and calculated LogP between 0 and 2:
    https://www.guidetopharmacology.org/services/ligands/substructure?smiles=Nc1cnc(Cl)c(N)n1&logpGt=0&logpLt=2
  10. Find all the pKi interaction data for approved drugs at GPCRs:
    https://www.guidetopharmacology.org/services/interactions?affinityType=pki&approved=true&targetType=GPCR
  11. Retrieve all diseases with OMIM database ID mapped:
    https://www.guidetopharmacology.org/services/diseases?database=OMIM
  12. Retrieve all diseases mapped to Disease Ontology ID 6688 (Autoimmune Lymphoproliferative syndrome):
    https://www.guidetopharmacology.org/services/diseases?database=DOID&accession=6688
  13. Retrieve all targets tagged in database as relevant to immunopharmacology (GtoImmuPdb):
    https://www.guidetopharmacology.org/services/targets?immuno=true
  14. Retrieve all ligands tagged in database as relevant to immunopharmacology (GtoImmuPdb):
    https://www.guidetopharmacology.org/services/ligands?type=immuno
  15. Retrieve all interaction data for Plasmodium species P. vivax:
    https://www.guidetopharmacology.org/services/interactions?species=Pv

Databases

* This is a list of the database names to use when searching for targets or ligands by accession number. For more information about these databases see the help page.

DatabaseDatabase name in GtoPdbTarget or ligand
BindingDB database of binding affinitiesBindingDBLigand
BitterDB database of bitter compoundsBitterDBTarget
BRENDA database of enzyme reactionsBRENDALigand
CAS Registry NumberCASLigand
Chemical Entities of Biological Interest (ChEBI)ChEBILigand
ChEMBL medicinal chemistry databaseChEMBLTarget & Ligand
NCBI Database for Short Genetic Variations (dbSNP)dbSNPTarget
Disease OntologyDOIDDisease
DrugBankDrugBankTarget & Ligand
Ensembl GeneEnsemblGeneTarget & Ligand
Ensembl ProteinEnsemblProteinTarget
Ensembl TranscriptEnsemblTranscriptTarget
NCBI Entrez GeneEntrezGeneTarget & Ligand
GPCRDBGPCRDBTarget
Human Metabolome Database (HMDB)HMDBLigand
HGNC database of human gene namesHGNCTarget
IMGT/mAb-DB database of therapeutic monoclonal antibodiesIMGTLigand
LIPID MAPS Lipidomics GatewayLipidMapsLigand
MEROPS peptidase databaseMEROPSTarget
Mouse Genome InformaticsMGITarget
Nuclear Receptor Signaling AtlasNURSATarget & Ligand
Online Mendelian Inheritance in Man (OMIM)OMIMTarget & Ligand & Disease
Orphanet database of rare diseasesOrphanetTarget & Disease
NCBI Protein database GI numbersProteinGITarget & Ligand
Protein Data Bank (PDB)PDBLigand
PubChem Compound Id (CID)PubChemCIDLigand
NCBI RefSeq NucleotideRefSeqNucleotideTarget & Ligand
NCBI RefSeq ProteinRefSeqProteinTarget & Ligand
Rat Genome DatabaseRGDTarget
UniProtKB protein resourceUniProtKBTarget & Ligand
UniProtKB variant databaseUniProtVariantTarget

HTTP response codes

This is a listing of specific HTTP response error codes which can be returned by the GtoPdb web services and their meanings.

HTTP response codeMeaningDescription
204No contentAn empty page and a 204 no content response usually mean there are no results to display for the given URL (i.e. no data in the requested database table).
303See otherRedirection to an alternative location for the requested data (e.g. the path to a ligand image).
404Not foundEither a resource with that address or an entity such as a ligand with the given identifier cannot be found.