Programmatic Access

Data in the ArrayExpress Archive, Gene Expression Atlas can be programmatically accessed using the following services:

• REST-style interface - to search for experiments in the Archive and gene expression profiles in the Warehouse
  
• SOAP Web Services API
  • for the Warehouse - Note that the Data Warehouse is a legacy database, please use the Atlas instead
  • for the Atlas - to search for gene expression summaries
• DAS data viewer to access gene expression profiles in the Warehouse

NOTE: The format of REST-style and Web Services changed in Sept 2008. To be notified of any future changes and extensions to the programmatic access please subscribe to the announcement list using the form below.

REST-style interface

Experiment search results can be retrieved either in parsable XML format or as an HTML-formatted web page.

XML format

Searching for experiments and data files in the ArrayExpress archive

Keywords can be used to search for specific experiments, with the results returned in an XML document, using URLs with the experiments term and keywords=X format. E.g.

To narrow the search by using more than one keyword, separate terms by + or & (acts as an AND) e.g.

To narrow search to experiments with samples of a particular species include the 'species' term

To retrieve the list of files associated with a set of experiments use the 'files' term in the URL

To retrieve a list of files for a particular experiment format the query as follows:

Also note:

• Accession number and keyword searches are case insensitive.
• Parts of words can also be searched e.g. colo will retrieve results with matches to both colon and colorectal (and also color, colony etc), unless there is a paramter wholewords=on in the query string e.g.

Retrieve information about all public experiments

To retrieve an xml file with information about all public experiments remove the keyword part of the search.

Accessing private experiments in the ArrayExpress archive

1. Use your client to retrieve the following URL (inserting the username and
   password provided to you by the ArrayExpress curators):
   http://www.ebi.ac.uk/microarray-as/ae/verify-login.txt?u=username&p=password
   If the login details are correct this will return a login token that is unique
   to your username, IP address and client. If the login fails you will get a
   blank page.
2. Set up 2 cookies for the domain http://www.ebi.ac.uk/ :
   AeLoggedUser = username
   AeLoginToken = login token from URL in step 1
3. Use these cookies when making all subsequent requests to ArrayExpress. It is important to use the same client that was used in step 1.

Format of XML documents

The XML document returned from a search lists how many experiments retrieved and then information about the experiments. Each experiment is in an <experiment></experiment> element. E.g.

Web pages

Retrieving web pages - archive experiment searches

Experiments in the ArrayExpress archive can be searched by accession, keyword or organism

To search by experiment accession:

To search by keyword enter the keyword as follows (%20 acts as an AND to narrow search using multiple keywords):

To search for experiments by species:

To combine keywords and species searches:

Retrieving web pages - warehouse expression profile searches

Expression profiles for genes can be searched in the warehouse by their associated identfiers. E.g.

Expression profiles can also be searched using keywords e.g.

This will return a list of genes that have the word 'cancer' anywhere in their annotation, and a list of experiments in the ArrayExpress warehouse that have cancer anywhere in their experiment title, description or sample annotation.

Gene searches can be further refined by adding additional keyword search terms or gene identifiers. E.g.

Format of web pages

Archive searches return a web page with a summary of the experiment information and links to the data files, protocols etc. e.g. http://www.ebi.ac.uk/arrayexpress/experiments/E-MEXP-31 returns:

Warehouse searches return either a web page of thumbnails if only one gene is matched, or a list of genes and experiments that match the search criteria. E.g. http://www.ebi.ac.uk/arrayexpress/q-aew/cancer%20BRCA1 returns:

Web Services

Overview

The ArrayExpress Data Warehouse has been replaced by the ArrayExpress Atlas. These web services are no longer maintained - please migrate to the Gene Expression Atlas

The AEW 7.10 Web Services release is a general-public *beta* release of SOAP Web Services for ArrayExpress warehouse of gene expression profiles. It provides some of the core functionality of the database for programmatic access.

The Web Services we publish are XML-RPC SOAP Web Services. The WSDL entry point for these is at http://www.ebi.ac.uk/microarray-as/aew/services/query?wsdl (see also http://www.ebi.ac.uk/microarray-as/aew/wsdl-view) .

The WSDL that is published at this link is self-documenting, i.e. each API entry point contains documentation on its use. The XML-RPC SOAP model allows ArrayExpress warehouse Web Services to be used in standard workflow tools such as Taverna, or via any SOAP client.

API Entry Points

The following Web Services are provided:

1. rankedExperimentsForGene(String geneIdentifier)

   Returns a ranked list of experiments for a given gene. The gene identifier is something that was returned by geneSearch, usually an Ensembl gene identifier, but in some cases a Uniprot id. The list is an array of strings, each of the format accession number:rank. The rank is an FDR-adjusted p-value from the differential expression analysis performed as part of ArrayExpress warehouse data curation procedure (see http://www.ebi.ac.uk/microarray/doc/help/warehouse_results.html#ranking for more details).

2. topGenesForExperiment(String exptAccnum, Integer numGenes)

   Returns a ranked list of genes for a given experiment, stopping at the given number of genes. The list is an array of strings, each of the same format as above, but you also get the experimental factor for each gene's p-value.

3. experimentSearch(String keyword)

   Returns a list of experiments (ArrayExpress accession numbers) matching (full-text search over descriptions and sample attributes) a keyword. Partial matches are supported.

4. geneSearch(String keyword)

   Returns a list of genes matching a keyword search, as above. Full-text search over all gene attributes is supported (Ensembl & Uniprot identifiers, OMIM, GO, etc.)

Further notes

This is a very incomplete API. Future releases will include methods for:

• Sample search
• Complete experiment attribute set retrieval
• Complete gene attribute set retrieval
• Complete sample attribute set retrieval
• Retrieval of gene expression data values for requested gene/sample/experiment combination (within one experiment)

We are happy to take requests from users for desired Web Services API functionality. Please email these to .

DAS data source

The ArrayExpress Warehouse also provides a DAS data source http://www.ebi.ac.uk/microarray-as/aew/das/dsn (through the BioSapiens Network of Excellence). You can use it to retrieve information by UniProt or Ensembl gene identifiers, formatted to be used in a DAS viewer (e.g., http://www.ensembl.org).

Any further questions, please see our FAQ.