PTGL API

Welcome to the PTGL API

Basics | Addressing data | Usage Examples | Metadata queries | Collection queries | Example API client code | Help, comments | Author, Imprint


The PTGL Application Programming Interface (API) allows you to quickly retrieve data from the PTGL programmatically. This page explains how to use the API.

A typical use case is that you want more data than you are willing to download manually by clicking in your web browser. You may, for example, have a list of 250 PDB chains, and you want the albe protein graphs for all of them in GML format.

If you are not a programmer, you may prefer the HTML interface of the PTGL.

Basics

This is a REST API, and you can query it with any HTTP client. There are specialized REST clients, but something like curl will do in principle. Of course, you can query this API with a programming language of your choice. We have some example PHP code to access the API here.

All data is served in JavaScript Object Notation (JSON) format. For graph data, you can chose between Graph Modelling Language (GML) format and JSON format. Images are available in PNG and SVG formats.

Data available via the API

You can retrieve protein graph (PG) and folding graph (FG) data in GML and JSON formats. You can also retrieve the linear notations (linnots) of a folding graph as a string. It is also possible to retrieve the graph images -- both the PG visualization and the 4 different linnot visualizations.

The PTGL is a protein topology database which works mainly on the level of a protein chain: a protein graph includes all the secondary structure elements (SSEs) of a chain. (Which SSEs types are included is determined by the graph type, e.g., the alpha graph only contains alpha helices, while the alpha-beta graph contains both alpha helices and beta strands.)

You may have guessed it, but all methods provided are GET. You cannot alter (insert, update, delete) any data on the server using this API.

Addressing data

All data must be retrieved via GET. Atm, no authentication is required to access the API.

Learn howto address: Protein graphs | Folding graphs | Linear notations | Motifs

Addressing Protein graphs and their visualization

The data is addressed by the following information for a Protein graph:

/pg/<pdbid>/<chain>/<graphtype>/<graphformat>


You can also get the visualization of a protein graph as an image:

/pgvis/<pdbid>/<chain>/<graphtype>/<imageformat>

You need all the info from the PG except for the <graphformat>, plus the following extra information:

Addressing Folding graphs and their visualization

A Folding graph (FG) is a single connected component of a protein graph (PG). To address a folding graph, you need: Folding graph query format:

/fg/<pdbid>/<chain>/<graphtype>/<fold>/<graphformat>


You can also get the visualization of a folding graph as an image. This will return the new DEF folding graph visualization, which shows the folding graph within the parent protein graph: the vertices and edges of the FG are colored, while the other (PG-only) vertices and edges are drawn in gray. See addressing Linear notations below if you want the ADJ, RED, SEQ or KEY notation visualization of the FG instead.

/fgvis/<pdbid>/<chain>/<graphtype>/<fold>/<imageformat>

You need all the info from the FG except for the <graphformat>, plus the following extra information:

Addressing Linear notations and their visualizations

There exist 4 different linear notation strings to describe the same folding graph. Each of them has a diffenerent visualization. To address a linear notation, you need:

/linnot/<pdbid>/<chain>/<graphtype>/<fold>/<linnot>


You can also get the visualization of a linear notation as an image:

/linnotvis/<pdbid>/<chain>/<graphtype>/<fold>/<linnot>/<imageformat>

You need all the info from the linnot, plus the following extra information: Note that the KEY notation is not defined for bifurcated graphs and may thus return the empty string for a fold.

Usage examples

Here are some example queries against the API:

Protein graphs:

Folding graphs: Linear notations:

Metadata queries

To automatically process all data of a certain type, it is very handy to know which data is available. For example, you may want to process all chains of a protein -- but how do you know the chain names? The same applies to the number of connected components (folding graphs) of a protein graph -- how do you know how many connected components a protein graph has? We also provide methods to get this information:

All chain names of a protein:

All folding graph numbers of a protein graph:

Collection queries

All queries presented so far were entity queries, i.e., they return data on a single object. We also provide some collection queries, which return some handy lists of objects. All of these return data in JSON format only:

A JSON list of all linear notation strings of a folding graph:

Motif queries


To query for PDB chains containing a motif, you need the following information:

Note that this returns a very long list for some motifs. The following names (in bold) are available: All of these return data in JSON format only:

A JSON list of all protein chains (e.g., '7timA') that contain a certain motif:

Example code to access this API

PHP

Here is some simple example code which queries this API from PHP, using libcurl. The code retrieves the ADJ linear notation string of the albe graph of 7tim chain A. Feel free to use and extend it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php
$url_linnot = 'http://ptgl.uni-frankfurt.de/api/index.php/linnot/7tim/A/albe/0/adj';
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url_linnot);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FAILONERROR, 1);

$result = curl_exec($curl);

if(curl_errno($curl)) {
    // TODO: handle error here
    echo 'ERROR: ' . curl_error($curl);
}
else {
    // TODO: do something with the result here
    // the result will be "{h,3ph,-2me,-3pe,-2pe,-2pe,-2pe,18pe,-2pe,-4pe,-3pe,2zh,3ph,2me}"
    echo "OK. adj string: " . json_decode($result);    
}
?>


BASH shell

We also provide a BASH shell script for Linux that will download the GML files for a list of proteins or chains. The list can be in a CSV file. The script and an example list is available for download here: bash_api_example.zip. The script comes without any warranty. Make sure you understand it and adapt it to your needs before usage. The script uses wget, awk, tr and other standard unix tools.

Comments, questions, bug reports, getting more help

The PTGL and the data this API serves are based on the VPLG software. If you need more help, you should use the VPLG help options listed at the VPLG sourceforge project page. There is a ticket system and a forum.

Author, Citing, Contact and Imprint

The PTGL REST API was written by Tim Schäfer at the MolBI group at Uni Frankfurt, Germany.

Please cite the PTGL if you use this API for scientific work.

Imprint.