API

Introduction

API Documentation

The documentation for the updated API in the form of OpenAPI specs can be found here

Note: The main difference from the old api is that results are retrieved in an asynchronous manner

Examples using curl

To start a phmmer search use this command

1
2
3
4
5
6
7
curl -s -X POST "https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/phmmer" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
    "database": "pdb",
    "input": ">2abl_A mol:protein length:163  ABL TYROSINE KINASE\\nMGPSENDPNLFVALYDFVASGDNTLSITKGEKLRVLGYNHNGEWCEAQTKNGQGWVPS"
  }'

Note: to preserve new lines use \\n

To retrieve the results from a search use this command

1
2
3
curl -s -X GET \
    "https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/result/8ebb1d5f-4457-4da8-808c-f811105c3654" \
    -H "Accept: application/json"

The following section demonstrates a more integrated way of starting a phmmer search and retrieving results.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#!/usr/bin/env bash

# Exit immediately if any command exits with a non-zero status
# Treat unset variables as an error, and pipes will fail if any command fails
set -euo pipefail

# Define the path to the input FASTA file
FASTA="path/to/input.fasta"
# Define the path to the output JSON file
OUTPUT="result.json"

# Perform a POST request to submit the FASTA sequence to the API and run an phmmer search
# The sequence is read from the FASTA file and escaped appropriately
RESPONSE=$(curl -s -X POST \
    "https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/phmmer" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "{\"database\":\"pdb\",\"input\":\"$(cat $FASTA | awk '{printf "%s\\n", $0}' | sed 's/"/\\"/g')\"}")

# Extract the job ID from the JSON response using grep and sed
# The job ID is returned in the response and will be used to check the status later
JOB_ID=$(echo $RESPONSE | grep -o '"id":[^,}]*' | sed 's/"id": *"//g' | sed 's/"//g')

# Start an infinite loop to periodically check the status of the job
while true; do
    # Perform a GET request to check the status of the job using the job ID
    RESPONSE=$(curl -s -X GET \
        "https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/result/$JOB_ID" \
        -H "Accept: application/json")

    # Extract the status field from the JSON response using grep and sed
    STATUS=$(echo "$RESPONSE" | grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:[[:space:]]*"//;s/"$//')

    # Check if the status is "SUCCESS"
    if [ "$STATUS" == "SUCCESS" ]; then
        # If successful, print a success message and save the response to a file
        echo "Job completed successfully!"
        echo $RESPONSE >$OUTPUT # Save the response (JSON) to the output file
        break                   # Exit the loop when the job is successful
    fi

    # Print the current status if it's not "SUCCESS"
    echo "Current status: $STATUS"

    # Sleep for 5 seconds before checking the status again
    sleep 5
done

Available services

phmmer searches

The main two input parameters to a phmmer search are a protein sequence and the target database, defined using the input and database parameters respectively. Other parameters for controlling the search are defined in the search section. If any of these parameters are omitted, then the default values for that parameter will be set.

Searches should be POST-ed to the following url:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/phmmer

hmmscan searches

Hmmscan also has two main parameters - a sequence and a profile HMM database - defined using the input and database parameters respectively. We currently offer Pfam only.

Searches should be POST-ed to the following url:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/hmmscan

hmmsearch searches

The input to hmmsearch on the web is either a multiple sequence alignment or a hidden Markov model in HMMER3 format. We do not support HMMER2 format as these HMMs are not forward compatible with HMMER3. When uploading a multiple sequence alignment, an HMM is built on the server using hmmbuild with the default parameters.

Searches should be POST-ed to the following url:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/hmmsearch

jackhmmer searches

Jackhmmer is an iterative search algorithm that can be initiated with a sequence, multiple sequence alignment or profile HMM. The number of iterations to run can be supplied as an additional parameter and will perform a succession of searches until the job has completed. Fetching the results is a little more complicated, as the search may finish before the number of iterations if it converges.

Searches should be POST-ed to the following url:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/search/jackhmmer

Results

Search results can be retrieved using the job identifier that is returned in your initial search response. The job identifier is a UUID (format such as 4162F712-1DD2-11B2-B17E-C09EFE1DC403). Thus, to retrieve your job, you can use the following URL in a GET request:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/result/{id}

Example:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/result/4162F712-1DD2-11B2-B17E-C09EFE1DC403

Taxonomy and domain views

The API may also be used to retrive the data behind the taxonomy and domain architecture tabs on the results page. For taxonomy the URL has the form:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/taxonomy/{id}/tree

Example:

curl -s -H "Content-type: application/json" 'https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/taxonomy/8D5B74A0-6158-11E7-B311-1331132D729D/tree'

For domain architecture, two endpoints are provided. The first returns an overview of all architectures:

https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/architecture/{id}

Example:

curl -s -H "Content-type: application/json" 'https://wwwdev.ebi.ac.uk/Tools/hmmer/api/v1/architecture/8D5B74A0-6158-11E7-B311-1331132D729D'

Batch searches

Batch searches are currently disabled.