API Documentation

This page contains documentation and examples for our API. This API can be used to query the Pogo database directly.

Introduction

A key feature of POGO is the ability for users to be able to mass query our database. Our web interface has a certain use-case, and we recognize that users may have different needs than our website provides. They might have a different workflow, need to feed our data through a pipeline, or download large sets of data.

In order to remedy this, we provide users not only with the ability to download our entire database, but also with the ability to directly query the database for information they are interested in.

Organization

POGO's database is internally represented by two tables. The data table contains comparison data between two genomes, and the taxonomy table containing taxonomic information about the genomes.

Our database's API returns JSON formatted arrays or CSV files, and uses REST's "GET" mechanism to work. POGO's database API is loosely based around SQL select statements, since we use MySQL as our database backend.

Query Basics

Queries are done by specifying certain GET variables in the URL. An example of this can be seen below, where we query the taxonomy table for all rows with the columns species, genome, and family.

To get more specific results we need to tell the database to return only rows that fit what we are interested in. As you saw above, we can tell the database what columns we are interested in, but we now need to tell it what columns we are interested in

The 'methods' section below explains how we can do just that.

Methods

Type

The Type argument tells the API which table you are querying, and is always required when using the API. There are only two options, "data" and "taxonomy".

The taxonomy table contains information about the different genomes that were compared.

Taxonomy Example: http://pogo.ece.drexel.edu/query.php?type=taxonomy&limit=10

The data table contains data from the comparisons.

Data Example: http://pogo.ece.drexel.edu/query.php?type=data&limit=10

Select

The Select argument allows you to choose which columns you are interested in. To know what columns are available please refer to the Properties section of this document.

If no results are returned, then all rows in the selected table are returned

This example returns the columns genus, species, ord, and superkingdom from the taxonomy table: http://pogo.ece.drexel.edu/query.php?type=taxonomy&select=genus,species,ord,superkingdom&limit=10

This example returns the columns id from data from the data table: http://pogo.ece.drexel.edu/query.php?type=data&select=id&limit=10

Where

The Where argument allows you to filter the rows based upon a statement. These operators and statements should be familiar to anyone with rudimentary knowledge of logic or programming.

At the bottom of this document are examples for different where statements

The operators we support are listed below

We also support other statements that allow users to do string comparisons.

Examples

Select all columns from rows where the genus is Bacillus http://pogo.ece.drexel.edu/query.php?type=taxonomy&where=genus='Bacillus'

Select all taxonomy where the genus contains 'Actino' http://pogo.ece.drexel.edu/query.php?type=taxonomy&where=genus like('Actino')

Select all data where the Genomic_Fluidity is over 90% http://pogo.ece.drexel.edu/query.php?type=data&where=Genomic_Fluidity>.90

Select all data where the Genomic_Fluidity is over 90% or less than 20% http://pogo.ece.drexel.edu/query.php?type=data&where=Genomic_Fluidity>.90 OR Genomic_Fluidity<.20

Warning: Order of Operations

Consider that the following statement could have multiple meanings: Select all taxonomy where the Genomic_Fluidity is over 90% or less than 20% and Average Amino Acid Identity is over 90%.

Using parentheses we can control the order of evaluation in a statement. This is the same as with math, inside to outside. It also follows the same style as most programming languages.

Here we have a statement where we select where Genomic_Fluidity is either over 90%, or is less than 20% and has an AAAI over 90%. http://pogo.ece.drexel.edu/query.php?type=data&where=(Genomic_Fluidity > .90) or (Genomic_Fluidity < .20 AND Average_Amino_Acid_Identity > .90 )

Limit

The Limit argument allows the user to specify how many results you want to return at maximum

Output

The Output argument allows you to specify if you want CSV or JSON output. By default a JSON array will be returned.

Array

The Array argument allows you to specify if you want either a JSON Associative Array, or a Indexed Array, if you are using JSON as your output type. For more information read this link.

This argument is optional, and the POGO database will return numerical arrays by default.

This is an example of returning an associative array in the data table

Properties

This section details the columns available in our data and taxonomy tables. Each column can be used in where statements, and in the select arguments.

Taxonomy Table

Our taxonomy table is collected from NCBI with some small changes.

Comparison Data

The comparison table contains all the information you see on the regular webpage, like orthologs, 16S_rRNA, and other marker genes.

Blast files

In order to get a tarball of blast files from our database, you need to query our download url. This is done in the same method as the regular query.

The ids variable corresponds to the "id" column in the comparison table.

This example requests a tarball containing blast files from comparisons with the id's 2354, 19201, and 623719.

Examples

Taxonomy Comparisons

 if (genome1_genus is A and genome2_genus is B)
 OR
 if (genome1_genus is B and genome2_genus is A)

 >>> Then show me the results

One Genus vs Another

One Genus vs Itself

One Species vs All Others

One Species vs Itself