Gene Expression Atlas APIs

Introduction

REST APIs

Atlas REST API provides all the results available in the main web application in a pragmatic, easy to use form - simple HTTP GET queries as input and either JSON or XML formats as output.

All REST API URLs now have the following general form:

http://<ATLAS>/api?<query>[&format=<json|xml>][&indent]

• format parameter specifies output format and can be eith xml or json for XML and JSON formats respectively.
• indent option allows you to get a pretty-formatted source useful for debugging purposes, so that results can be viewed in text editor. DO NOT use this option in production as it increases bandwidth use and significantly increases response and processing time.

JSON output format also supports JSONP-style callbacks, which should be specified with argument callback=callbackName. In this case resulting JSON output wil be wrapped into a callback function call, ready to be evaluated bythe requesting client's <script> tag. For example:

http://<ATLAS>/api?<query>&format=json&callback=processResult

will render

processResult({ ...query result data... })

This could be useful to create cross-site AJAX mashups using Atlas data. Please refer to this HTML/Javascript code example:

        function processData(data) {
            if(data.error) {
                alert(data.error);
                return;
            }

            alert('Experiment accession: ' + data.experimentInfo.accession + ', description: ' + data.experimentInfo.description);
        }

        function queryExperiment(experimentId) {
            var head = document.getElementsByTagName('head');
            var script = document.createElement('script');
            script.type = "text/javascript";
            script.src = atlasHomeUrl + "/api?experiment="+escape(experimentId)+"&format=json&callback=processData";
            head[0].appendChild(script);
        }

        ...
        <input type="button" value="Show experiment" onclick="queryExperiment('E-AFMX-1')">

Gene queries

The gene query interface resembles the original "structured query" interface available through the web and allows to combine gene properties queries with conditions. Query parameters are passed through a set of HTTP GET URL parameter name=value pairs and should be URL-escaped as usual (%-based encoding, like %20%30%40).

Gene filter parameters have the format of gene<Property>Is=... or gene<Property>IsNot=..., where <Property> should be one of:

• Name - Gene name
• Goterm - Gene Ontology Term
• Interproterm - InterPro Term
• Disease - Gene-Disease Assocation
• Keyword - Gene Keyword
• Protein - Protein

• Dbxref - Other Database Cross-Refs
• Embl - EMBL-Bank ID
• Ensfamily - Ensembl Family
• Ensgene - Ensembl Gene ID

• Ensprotein - Ensembl Protein ID
• Enstranscript - Ensembl Transcript ID
• Goid - Gene Ontology ID
• Image - IMAGE ID
• Interproid - InterPro ID
• Locuslink - Entrez Gene ID

• Omimid - OMIM ID
• Orf - ORF
• Refseq - RefSeq ID
• Unigene - UniGene ID
• Uniprot - UniProt Accession

• Hmdb - HMDB ID
• Chebi - ChEBI ID
• Cas - CAS
• Uniprotmetenz - Uniprotmetenz
• Gene - Gene Name or Identifier
• Synonym - Gene Synonym

All fields are searched if <Property> is omitted.

Examples:

http://<ATLAS>/api?geneGotermIs=p53+binding&geneDisease=cancer
http://<ATLAS>/api?geneIs=ASPM
http://<ATLAS>/api?geneIsNot=cell+cycle
http://<ATLAS>/api?geneIs=ENSMUSG0000012344

Condition queries

Condition queries can be combined with gene queries to filter result genes according to their expression statistics. Condition parameters have the format <up|down|updown>In<Factor>=... where <Factor> (optional, if omitted, all condition properties are searched) is one of:

• Anything - Any experimental factor
• Experiment - An experiment accession, such as E-AFMX-5
• Efo - An Factor Ontology accession, e.g., EFO_0001359 (diabetes mellitus)

or, more specifically:

• Age - Age
• Biometric - Biometric measurement
• Cellline - Cell line
• Celltype - Cell type
• Clinhistory - Clinical history
• Clininfo - Clinical info
• Clintreatment - Clinical treatment
• Compound - Compound treatment
• Cultivar - Cultivar
• Devstage - Developmental stage
• Diseaseloc - Disease location
• Diseasestaging - Disease staging
• Diseasestate - Disease state
• Dose - Dose
• Ecotype - Ecotype
• Envhistory - Environmental history
• Familyhistory - Family history
• Genmodif - Gene modification
• Genotype - Genotype
• Growthcondition - Growth condition
• Histology - Histology
• Indgeneticchar - Genotype
• Individual - Individual
• Infect - Infection
• Initialtime - Initial time
• Injury - Injury
• Light - Light
• MaterialType - Material type
• Media - Media
• Observation - Observation
• Organism - Organism
• Organismpart - Organism part
• Organismstatus - Organism status
• Performer - Performer
• Phenotype - Phenotype
• Population - Population
• Protocoltype - Protocol type
• Qcdescrtype - QC description
• Replicate - Replicate
• RNAi - RNAi
• Sex - Sex
• Sourceprovider - Source provider
• Strainorline - Strain or line
• Targetcelltype - Target cell type
• Temperature - Temperature
• Test - Test
• Testresult - Test result
• Testtype - Test type
• Time - Time
• Tumorgrading - Tumor grading
• Vehicle - Vehicle
• Generation - Generation

All factors are searched if <Factor> is omitted.

If you want to get genes, which are up or down only in one specified value of factor and alternatively expressed in all other values of the same factor, it is possible to specify:

• upOnlyIn<factor>=<factor value>
• downOnlyIn<factor>=<factor value>

This feature DOES NOT work for EFO and "any" factor, existing factor must be specified.

It is also possible to limit results only for those genes which are up/down regulated in more than specified number of experiments in specified condition:

• up<N>In<factor>=<factor value>
• down<N>In<factor>=<factor value>

Examples:

http://<ATLAS>/api?upIn=liver
http://<ATLAS>/api?updownInOrganismpart=heart
http://<ATLAS>/api?upOnlyInOrganismpart=heart
http://<ATLAS>/api?up3In=cancer
http://<ATLAS>/api?down5InSex=male
http://<ATLAS>/api?downInOrgansimpart=kidney&upInSex=male
http://<ATLAS>/api?geneIs=p53&downInOrgansimpart=kidney&upInSex=male

Organisms

User can limit output genes to specified organisms using one or more species parameters. Examples:

http://<ATLAS>/api?upIn=liver&species=Mus+Musculus
http://<ATLAS>/api?upIn=liver&species=Mus+Musculus&species=Homo+Sapiens

As of now supported organisms are following:

• Arabidopsis thaliana
• Bacillus subtilis
• Caenorhabditis elegans
• Danio rerio
• Drosophila melanogaster
• Homo sapiens
• Mus musculus
• Rattus norvegicus
• Saccharomyces cerevisiae
• Schizosaccharomyces pombe

Limiting number of result genes

There are two parameters to control result output:

• start specifies starting number of gene in results, default value is 0.
• rows limits number of genes to output (starting from start), default (and maximum allowed) value is 50.

Using these two parameters it is possible to get gene results in "pages". To calculate exact amount of pages, one could use results.totalResults value from the output (see below), which is total amount of genes found by the query.

Examples:

http://<ATLAS>/api?upIn=liver&start=200&rows=50

Output

The query output structure is self-explanatory, and it can be tested using a plain web browser just pointing it to an API URL and adding an &indent argument. Here is an example of the result set rendered by the gene query http://<ATLAS>/api?geneIs=ENSG00000159216&format=json&indent:

{
    "results" : [
        {
            "gene" : {
                "id" : "ENSG00000159216",
                "name" : "RUNX1",
                "orthologs" : [
                    "B0414.2",
                    "ENSMUSG00000022952",
                    "ENSRNOG00000001704"
                ],
                "ensemblGeneId" : "ENSG00000159216",
                "goTerms" : [
                    "ATP binding",
                    "chloride ion binding",
                    "nucleus",
                    ...
                ],
                "interProIds" : [
                    "IPR000040",
                    "IPR012346",
                    ...
                ],
                "interProTerms" : [
                    "Runx inhibition",
                    "Transcription factor, Runt-related, RUNX",
                    ...
                ],
                "keyword" : [
                    "3D-structure",
                    "Alternative splicing",
                    ...
                ],
                "diseases" : [
                    "Leukemia, acute myeloid",
                    "Platelet disorder, familial, with associated myeloid malignancy",
                    "Rheumatoid arthritis, susceptibility to"
                ],
                "uniprotIds" : [
                    "Q01196"
                ],
                "synonyms" : [
                    "AML1",
                    "CBFA2",
                    "RUNX1"
                ],
                "goIds" : [
                    "GO:0003700",
                    ...
                ],
                "emblIds" : [
                    "AP000330",
                    ...
                ],
                "ensemblProteinIds" : [
                    "ENSP00000300305",
                    ...
                ],
                "omimiIds" : [
                    "151385",
                    "601399"
                ],
                "refseqIds" : [
                    "NM_001001890",
                    "NM_001122607",
                    "NM_001754"
                ],
                "unigeneIds" : [
                    "Hs.149261",
                    ...
                ]
            },
            "expressions" : [
                {
                    "ef" : "RNAi",
                    "efv" : "SIM2s",
                    "experiments" : [
                        {
                            "pvalue" : 2.44739812717842E-6,
                            "expression" : "UP",
                            "accession" : "E-MEXP-101"
                        }
                    ],
                    "upExperiments" : 1,
                    "downExperiments" : 0,
                    "upPvalue" : 2.4473981738992734E-6,
                    "downPvalue" : 0.0
                },
                {
                    "efoTerm" : "T cell",
                    "efoId" : "EFO_0000208",
                    "experiments" : [
                        {
                            "pvalue" : 0.0209469933341716,
                            "expression" : "DOWN",
                            "accession" : "E-AFMX-5"
                        },
                        {
                            "pvalue" : 0.0261270675699093,
                            "expression" : "DOWN",
                            "accession" : "E-GEOD-6053"
                        }
                    ],
                    "upExperiments" : 0,
                    "downExperiments" : 2,
                    "upPvalue" : 0.0,
                    "downPvalue" : 0.020946992561221123
                },
                ....
            ]
        }
    ],
    "totalResults" : 1,
    "numberOfResults" : 1,
    "startingFrom" : 0
}

The XML output has similar structure and is meant to be processed with either XSLT or software modules, similar to Perl or Ruby's XML::Simple and similar, transforming it to a tree of objects.

<?xml version="1.0" encoding="utf-8"?>
<atlasResponse>
    <results>
        <result>
            <gene>
                <id>ENSG00000159216</id>
                <name>RUNX1</name>
                <orthologs>
                    <ortholog>B0414.2</ortholog>
                    <ortholog>ENSMUSG00000022952</ortholog>
                    <ortholog>ENSRNOG00000001704</ortholog>
                </orthologs>
                <ensemblGeneId>ENSG00000159216</ensemblGeneId>
                <goTerms>
                    <goTerm>ATP binding</goTerm>
                    <goTerm>chloride ion binding</goTerm>
                    ...
                </goTerms>
                <interProIds>
                    <interProId>IPR000040</interProId>
                    <interProId>IPR012346</interProId>
                    ...
                </interProIds>
                <interProTerms>
                    <interProTerm>Runx inhibition</interProTerm>
                    <interProTerm>Transcription factor, Runt-related, RUNX</interProTerm>
                    ...
                </interProTerms>
                <keywords>
                    <keyword>3D-structure</keyword>
                    <keyword>Alternative splicing</keyword>
                    ...
                </keywords>
                <diseases>
                    <disease>Leukemia, acute myeloid</disease>
                    <disease>Platelet disorder, familial, with associated myeloid malignancy</disease>
                    <disease>Rheumatoid arthritis, susceptibility to</disease>
                </diseases>
                <uniprotIds>
                    <uniprotId>Q01196</uniprotId>
                </uniprotIds>
                <synonyms>
                    <synonym>AML1</synonym>
                    <synonym>CBFA2</synonym>
                    <synonym>RUNX1</synonym>
                </synonyms>
                <goIds>
                    <goId>GO:0003700</goId>
                    <goId>GO:0005515</goId>
                    ...
                </goIds>
                <emblIds>
                    <emblId>AP000330</emblId>
                    <emblId>BC136381</emblId>
                    ...
                </emblIds>
                <ensemblProteinIds>
                    <ensemblProteinId>ENSP00000300305</ensemblProteinId>
                    ...
                </ensemblProteinIds>
                <omimiIds>
                    <omimiId>151385</omimiId>
                    <omimiId>601399</omimiId>
                </omimiIds>
                <refseqIds>
                    <refseqId>NM_001001890</refseqId>
                    <refseqId>NM_001122607</refseqId>
                    <refseqId>NM_001754</refseqId>
                </refseqIds>
                <unigeneIds>
                    <unigeneId>Hs.149261</unigeneId>
                    ...
                </unigeneIds>
            </gene>
            <expressions>
                <expression>
                    <ef>RNAi</ef>
                    <efv>SIM2s</efv>
                    <experiments>
                        <experiment>
                            <pvalue>2.44739812717842E-6</pvalue>
                            <expression>UP</expression>
                            <accession>E-MEXP-101</accession>
                        </experiment>
                    </experiments>
                    <upExperiments>1</upExperiments>
                    <downExperiments>0</downExperiments>
                    <upPvalue>2.4473981738992734E-6</upPvalue>
                    <downPvalue>0.0</downPvalue>
                </expression>
                <expression>
                    <efoTerm>GLI56</efoTerm>
                    <efoId>EFO_0001104</efoId>
                    <experiments>
                        <experiment>
                            <pvalue>0.00340485089589589</pvalue>
                            <expression>UP</expression>
                            <accession>E-GEOD-4717</accession>
                        </experiment>
                    </experiments>
                    <upExperiments>1</upExperiments>
                    <downExperiments>0</downExperiments>
                    <upPvalue>0.0034048508387058973</upPvalue>
                    <downPvalue>0.0</downPvalue>
                </expression>
                ...
            </expressions>
        </result>
    </results>
    <totalResults>1</totalResults>
    <numberOfResults>1</numberOfResults>
    <startingFrom>0</startingFrom>
</atlasResponse>

Experiments query

To search for experiments one can use a set of conditions similar to genes structured query. All conditions are joined with AND operator.

• experiment=<keyword1 keyword2 ...> conditions matches experiments, containing one of space separated keywords in accession, type or description
• experimentHasFactor=<factor1 factor2 ...> condition matches experiments which have one of space separated factors as experimental factor
• experimentHas<Factor>=<value1 value2 ...> condition matches experiments which have one of space separated values as experimental factor's <Factor> value for any of the assays
• experimentHasAnyFactor=<value1 value2 ...> condition matches experiments which have one of space separated values as any experimental factor's value for any of the assays

A special keyword value experiment=listAll can be used to list all available experiments.

The query may be accompanied with one or many gene=<GeneIdentifier> arguments to get expression details of specified genes in matching experiments. <GeneIdentifier> can be magic value topN, where N is the number of top N highly expressed genes in each experiment.

Note: topN functionality has been temporarily removed - 10 genes are always returned when no gene=<GeneIdentifier> arguments were specified. The topN functionality will be re-instated in a future Atlas release.

Similar to gene query, there are two parameters to control result output:

• start specifies starting number of experiments in results, default value is 0.
• rows limits number of experiments to output (starting from start), default value is 10.

• experimentInfoOnly limits amount of output to just experimentInfo section (see below in output example), this is useful if you need to

just a list of experiment accessions and titles for particular query.

Using these two parameters it is possible to get experiment results in "pages". To calculate exact amount of pages, one could use results.totalResults value from the output, which is total amount of experiments found by the query.

Examples:

http://<ATLAS>/api?experiment=E-AFMX-1&gene=top5
http://<ATLAS>/api?experiment=cell
http://<ATLAS>/api?experimentHasOrganismpart=lung
http://<ATLAS>/api?experimentHasDiseasestate=normal&experiment=cancer&start=10&rows=10
http://<ATLAS>/api?experimentHasFactor=celltype&experiment=cycle&gene=top10
http://<ATLAS>/api?experiment=E-AFMX-5&gene=ENSG00000160766&gene=ENSG00000166337&format=xml
http://<ATLAS>/api?experiment=listAll&experimentInfoOnly

Output is the list of experiments' details. The geneExpressions section contains actual microarray expression values for all design elements for the specified gene(s). assayIds array contains a series of assay IDs in the same order in which expression values will be in the corresponding designElement arrays.

geneExpressionStatistics section contains Atlas expression analytics results for design elements where it is available.

<?xml version="1.0" encoding="utf-8"?>
<atlasResponse>
 <results>
  <result>
    <geneExpressions>
        <arrayDesign accession="A-AFFY-33">
            <assayIds>0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 ... </assayIds>
            <genes>
                <gene id="ENSG00000160766">
                    <designElement id="17599">19.6 62.3 132.8 101.2 373.6 47.2 114.6 50.8 65.9 21.4 26.4 24.4 ... </designElement>
                </gene>
            </genes>
        </arrayDesign>
        <arrayDesign accession="A-AFFY-40">
            <assayIds>158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 ... </assayIds>
            <genes/>
        </arrayDesign>
    </geneExpressions>
    <experimentInfo>
        <accession>E-AFMX-5</accession>
        <description>Transcription profiling of human cell lines and tissues (GNF/Novartis)</description>
        <types>
            <type>organism_part_comparison_design</type>
        </types>
    </experimentInfo>
    <experimentOrganisms>
        <organism>Homo sapiens</organism>
    </experimentOrganisms>
    <experimentDesign>
        <experimentalFactors>
            <experimentalFactor>diseasestate</experimentalFactor>
            <experimentalFactor>celltype</experimentalFactor>
            <experimentalFactor>organismpart</experimentalFactor>
        </experimentalFactors>
        <sampleCharacteristics>
            <sampleCharacteristic>sex</sampleCharacteristic>
            <sampleCharacteristic>age</sampleCharacteristic>
            <sampleCharacteristic>observation</sampleCharacteristic>
            <sampleCharacteristic>diseasestate</sampleCharacteristic>
            <sampleCharacteristic>clinhistory</sampleCharacteristic>
            <sampleCharacteristic>devstage</sampleCharacteristic>
            <sampleCharacteristic>targetcelltype</sampleCharacteristic>
            <sampleCharacteristic>organismpart</sampleCharacteristic>
        </sampleCharacteristics>
        <arrayDesigns>
            <arrayDesign>
                <accession>A-AFFY-33</accession>
            </arrayDesign>
            <arrayDesign>
                <accession>A-AFFY-40</accession>
            </arrayDesign>
        </arrayDesigns>
        <samples>
            <sample>
                <id>0</id>
                <sampleCharacteristics>
                    <sex/>
                    <age/>
                    <diseasestate/>
                    <observation/>
                    <clinhistory/>
                    <devstage>adult</devstage>
                    <targetcelltype/>
                    <organismpart>thymus</organismpart>
                </sampleCharacteristics>
                <relatedAssays>
                    <assayId>26</assayId>
                </relatedAssays>
            </sample>
            <sample>
                <id>1</id>
                <sampleCharacteristics>
                    <sex/>
                    <age/>
                    <diseasestate/>
                    <observation/>
                    <clinhistory/>
                    <devstage>adult</devstage>
                    <targetcelltype/>
                    <organismpart>thymus</organismpart>
                </sampleCharacteristics>
                <relatedAssays>
                    <assayId>42</assayId>
                </relatedAssays>
            </sample>
            ...
        </samples>
        <assays>
            <assay>
                <id>0</id>
                <factorValues>
                    <diseasestate/>
                    <celltype/>
                    <organismpart>lung</organismpart>
                </factorValues>
                <arrayDesign>A-AFFY-33</arrayDesign>
                <relatedSamples>
                    <sampleId>112</sampleId>
                </relatedSamples>
            </assay>
            <assay>
                <id>1</id>
                <factorValues>
                    <diseasestate/>
                    <celltype/>
                    <organismpart>heart</organismpart>
                </factorValues>
                <arrayDesign>A-AFFY-33</arrayDesign>
                <relatedSamples>
                    <sampleId>62</sampleId>
                </relatedSamples>
            </assay>
            ...
        </assays>
    </experimentDesign>
    <geneExpressionStatistics>
        <arrayDesign accession="A-AFFY-33">
            <genes>
                <gene id="ENSG00000160766">
                    <designElement id="17599">
                        <expression>
                            <ef>organismpart</ef>
                            <efv>appendix</efv>
                            <stat>
                                <expression>UP</expression>
                                <pvalue>0.00892422770197655</pvalue>
                                <tstat>3.42359698327164</tstat>
                            </stat>
                        </expression>
                        ...
                    </designElement>
                </gene>
            </genes>
        </arrayDesign>
        <arrayDesign accession="A-AFFY-40">
            <genes/>
        </arrayDesign>
    </geneExpressionStatistics>
  </result>
  ...
 </results>
 <totalResults>20</totalResults>
 <numberOfResults>10</numberOfResults>
 <startingFrom>0</startingFrom>
</atlasResponse>

Error output

If an error occurred in the processing of the query, the output will contain an error message.

For example, for JSON:

{
    "error" : "Empty query specified"
}

For XML:

<?xml version="1.0" encoding="utf-8"?>
<atlasResponse>
    <error>Empty query specified</error>
</atlasResponse>

API links

On every Atlas result page you can find a "REST API" link, showing REST API URLs corresponding to results being displayed. So, it is easy to integrate interactive results into your program for further processing.

Additional Resources

• Details about the construction of the Atlas
• Programmatic access to the Atlas
• Frequently asked questions

• Mailing list. The Atlas mailing list is arrayexpress-atlas@ebi.ac.uk. You can send email with help requests, comments or improvement suggestions to this address. To subscribe or view list archives go to http://listserver.ebi.ac.uk/mailman/listinfo/arrayexpress-atlas.
• Blog. Read the Atlas blog at http://arrayexpress-atlas.blogspot.com for the latest news and views from the cockpit.
• About the microarray team