gh-k-dense-ai-claude-scientific-skills-scientific-skills/skills/opentargets-database/references/api_reference.md

Open Targets Platform API Reference

API Endpoint

https://api.platform.opentargets.org/api/v4/graphql

Interactive GraphQL playground with documentation:

https://api.platform.opentargets.org/api/v4/graphql/browser

Access Methods

The Open Targets Platform provides multiple access methods:

1. GraphQL API - Best for single entity queries and flexible data retrieval
2. Web Interface - Interactive platform at https://platform.opentargets.org
3. Data Downloads - FTP at https://ftp.ebi.ac.uk/pub/databases/opentargets/platform/
4. Google BigQuery - For large-scale systematic queries

Authentication

No authentication is required for the GraphQL API. All data is freely accessible.

Rate Limits

For systematic queries involving multiple targets or diseases, use dataset downloads or BigQuery instead of repeated API calls. The API is optimized for single-entity and exploratory queries.

GraphQL Query Structure

GraphQL queries consist of:

1. Query operation with optional variables
2. Field selection (request only needed fields)
3. Nested entity traversal

Basic Python Example

import requests
import json

# Define the query
query_string = """
  query target($ensemblId: String!){
    target(ensemblId: $ensemblId){
      id
      approvedSymbol
      biotype
      geneticConstraint {
        constraintType
        exp
        obs
        score
      }
    }
  }
"""

# Define variables
variables = {"ensemblId": "ENSG00000169083"}

# Make the request
base_url = "https://api.platform.opentargets.org/api/v4/graphql"
response = requests.post(base_url, json={"query": query_string, "variables": variables})
data = json.loads(response.text)
print(data)

Available Query Endpoints

/target

Retrieve gene annotations, tractability assessments, and disease associations.

Common fields:

• id - Ensembl gene ID
• approvedSymbol - HGNC gene symbol
• approvedName - Full gene name
• biotype - Gene type (protein_coding, etc.)
• tractability - Druggability assessment
• safetyLiabilities - Safety information
• expressions - Baseline expression data
• knownDrugs - Approved/clinical drugs
• associatedDiseases - Disease associations with evidence

/disease

Retrieve disease/phenotype data, known drugs, and clinical information.

Common fields:

• id - EFO disease identifier
• name - Disease name
• description - Disease description
• therapeuticAreas - High-level disease categories
• synonyms - Alternative names
• knownDrugs - Drugs indicated for disease
• associatedTargets - Target associations with evidence

/drug

Retrieve compound details, mechanisms of action, and pharmacovigilance data.

Common fields:

• id - ChEMBL identifier
• name - Drug name
• drugType - Small molecule, antibody, etc.
• maximumClinicalTrialPhase - Development stage
• indications - Disease indications
• mechanismsOfAction - Target mechanisms
• adverseEvents - Pharmacovigilance data

/search

Search across all entities (targets, diseases, drugs).

Parameters:

• queryString - Search term
• entityNames - Filter by entity type(s)
• page - Pagination

/associationDiseaseIndirect

Retrieve target-disease associations including indirect evidence from disease descendants in ontology.

Key fields:

• rows - Association records with scores
• aggregations - Aggregated statistics

Example Queries

Query 1: Get target information with disease associations

query = """
  query targetInfo($ensemblId: String!) {
    target(ensemblId: $ensemblId) {
      approvedSymbol
      approvedName
      tractability {
        label
        modality
        value
      }
      associatedDiseases(page: {size: 10}) {
        rows {
          disease {
            name
          }
          score
          datatypeScores {
            componentId
            score
          }
        }
      }
    }
  }
"""
variables = {"ensemblId": "ENSG00000157764"}

Query 2: Search for diseases

query = """
  query searchDiseases($queryString: String!) {
    search(queryString: $queryString, entityNames: ["disease"]) {
      hits {
        id
        entity
        name
        description
      }
    }
  }
"""
variables = {"queryString": "alzheimer"}

Query 3: Get evidence for target-disease pair

query = """
  query evidences($ensemblId: String!, $efoId: String!) {
    disease(efoId: $efoId) {
      evidences(ensemblIds: [$ensemblId], size: 100) {
        rows {
          datasourceId
          datatypeId
          score
          studyId
          literature
        }
      }
    }
  }
"""
variables = {"ensemblId": "ENSG00000157764", "efoId": "EFO_0000249"}

Query 4: Get known drugs for a disease

query = """
  query knownDrugs($efoId: String!) {
    disease(efoId: $efoId) {
      knownDrugs {
        uniqueDrugs
        rows {
          drug {
            name
            id
          }
          targets {
            approvedSymbol
          }
          phase
          status
        }
      }
    }
  }
"""
variables = {"efoId": "EFO_0000249"}

Error Handling

GraphQL returns status code 200 even for errors. Check the response structure:

if 'errors' in response_data:
    print(f"GraphQL errors: {response_data['errors']}")
else:
    print(f"Data: {response_data['data']}")

Best Practices

1. Request only needed fields - Minimize data transfer and improve response time
2. Use variables - Make queries reusable and safer
3. Handle pagination - Most list fields support pagination with page: {size: N, index: M}
4. Explore the schema - Use the GraphQL browser to discover available fields
5. Batch related queries - Combine multiple entity fetches in a single query when possible
6. Cache results - Store frequently accessed data locally to reduce API calls
7. Use BigQuery for bulk - Switch to BigQuery/downloads for systematic analyses

Data Licensing

All Open Targets Platform data is freely available. When using the data in research or commercial products, cite the latest publication:

Ochoa, D. et al. (2025) Open Targets Platform: facilitating therapeutic hypotheses building in drug discovery. Nucleic Acids Research, 53(D1):D1467-D1477.