WS

Integration of the bioinformatics Web services

http://togows.org/entry/database/entry_id[,entry_id2,...][/field][.format]

TogoWS API documentation

TogoWS provides uniformed REST API for accessing major bioinformatics data resources and data formats.

REST API conventions

TogoWS REST API currently supports following functionalities. Many of those features can be easily tried out at the top page.

• Entry http://togows.org/entry/database/entry_id[,entry_id2,...][/field][.format] (HTTP GET)
• Search http://togows.org/search/database/query+string[/offset,limit][.format] (HTTP GET)
• Convert http://togows.org/convert/data_source.format (HTTP POST)
• External API http://togows.org/api/service/database/table/column=value[/offset,limit][.format] (HTTP GET)

Entry

Entry retrieval REST API can be used to obtain database entries, extract a field content and convert the data format.

• Synopsis
  • http://togows.org/entry/database/entry_id[,entry_id2,...][/field][.format]
• Multiple entries
  • Multiple entries can be retrieved at once by concatenating identifiers with ',' (100 entries at maximum)
• Options
  • List of available databases: http://togows.org/entry/ (some have alias for short in the second column)
  • List of available fields: http://togows.org/entry/database?fields
  • List of available formats: http://togows.org/entry/database?formats
  • Splice of a nucleotide sequence: http://togows.org/entry/database/seq/location
• Errors
  • 400 Bad Request (HTTP error): requested URI or the database was invalid
  • 404 Not Found (HTTP error): requested entry was not found
• Examples

  % wget http://togows.org/entry/uniprot/BRCA2_HUMAN
  % wget http://togows.org/entry/uniprot/ACT_YEAST,ACT_SCHPO.fasta
  % wget http://togows.org/entry/nucleotide/NC_001138.gff
  % wget 'http://togows.org/entry/nucleotide/NC_001138/seq/complement(join(53260..54377,54687..54696))' # Yeast ACT1 gene
  % wget http://togows.org/entry/pubmed/20472643
  % wget http://togows.org/entry/pubmed/20472643/authors.json
  

Search

Database search REST API can be used to obtain a list of entry identifiers or a number of results by a keyword search.

• Synopsis
  • http://togows.org/search/database/query+string[/offset,limit][.format]
• Query string
  • Format of the "query string" is just a simple text (spaces can be replaced with '+' or '%20')
• Options
  • List of available databases: http://togows.org/search/ (some have alias for short in the second column)
  • List of available formats: http://togows.org/search/database?format
  • Limit the number of results: http://togows.org/search/database/query+string/offset,limit
  • Count the number of results: http://togows.org/search/database/query+string/count
• Errors
  • 400 Bad Request (HTTP error): requested URI or the database was invalid
  • 404 Not Found (HTTP error): requested entry had no results
• Examples

  % wget http://togows.org/search/uniprot/lung+cancer
  % wget http://togows.org/search/uniprot/lung+cancer/1,10
  % wget http://togows.org/search/uniprot/lung+cancer/11,5.html
  % wget http://togows.org/search/uniprot/lung+cancer/16,5.json
  % wget http://togows.org/search/uniprot/lung+cancer/count
  

Convert

Data format conversion REST API can be used to convert file formats.

• Synopsis
  • http://togows.org/convert/data_source.format
• Protocol
  • Use the HTTP POST protocol to upload your data as a text
• Options
  • List of available converters: http://togows.org/convert/ (description of these formats can be found here and here)
• Errors
  • 400 Bad Request (HTTP error): requested URI was invalid
  • 404 Not Found (HTTP error): requested data_source.format is not supported
• Examples

  % wget http://togows.org/entry/nucleotide/J00231
  % wget http://togows.org/convert/genbank.gff --post-file=J00231
  

External API

External API provides REST API for accessing non-Web service based external data sources. TogoWS currently supports UCSC databases.

UCSC API

UCSC API internally uses the Ruby UCSC API library which directly accesses to the public MySQL database provided by the UCSC. Although UCSC uses 0-based coordinates, biological 1-based positions are accepted and commas are omitted in the UCSC REST API.

• Synopsis
  • http://togows.org/api/ucsc/database/table/column[!]=value[;column2[!]=value2;...][/offset,limit][.format]
• Options
  • List of available databases: http://togows.org/api/ucsc[.json]
  • List of available tables: http://togows.org/api/ucsc/database[.json]
  • List of available columns: http://togows.org/api/ucsc/database/table[.json] (example data will be shown in the second column)
  • Obtain a limited number of results: http://togows.org/api/ucsc/database/table/offset,limit[.json]
• Keyword search
  • Find rows having a keyword in a given column: http://togows.org/api/ucsc/database/table/column=value[/offset,limit][.json]
  • Find rows not having a keyword in a given column: http://togows.org/api/ucsc/database/table/column!=value[/offset,limit][.json]
  • Filtering by multiple conditions: http://togows.org/api/ucsc/database/table/column[!]=value[;column2[!]=value2;...][/offset,limit][.json]
• Range search
  • Find rows within a range: http://togows.org/api/ucsc/database/table/chromosome:from-to[.json] (default to inclusive)
  • Include rows straddle over a boundary: http://togows.org/api/ucsc/database/table/inclusive/chromosome:from-to[.json]
  • Exclude rows straddle over a boundary: http://togows.org/api/ucsc/database/table/exclusive/chromosome:from-to[.json]
• Gene table (refGene, knownGene, ensGene, wgEncode etc.)
  • CDS positions: http://togows.org/api/ucsc/database/refGene/name[2]=value/cds[.json]
  • Exon positions: http://togows.org/api/ucsc/database/refGene/name[2]=value/exon[.json]
  • Intron positions: http://togows.org/api/ucsc/database/refGene/name[2]=value/intron[.json]
• bigWig table
  • Corresponding file name: http://togows.org/api/ucsc/database/bigWig
  • bigWigInfo output: http://togows.org/api/ucsc/database/bigWig/info
  • bigWigSummary output: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor (default to mean)
    • Mean: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor/mean
    • Minimum: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor/min
    • Maximum: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor/max
    • Coverage: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor/coverage
    • Standard deviation: http://togows.org/api/ucsc/database/bigWig/chromosome:from-to/divisor/std
• bigBed table
  • Corresponding file name: http://togows.org/api/ucsc/database/bigBed
  • bigBedInfo output: http://togows.org/api/ucsc/database/bigBed/info
  • bigBedSummary output: http://togows.org/api/ucsc/database/bigBed/chromosome:from-to/divisor (default to coverage)
    • Mean: http://togows.org/api/ucsc/database/bigBed/chromosome:from-to/divisor/mean
    • Minimum: http://togows.org/api/ucsc/database/bigBed/chromosome:from-to/divisor/min
    • Maximum: http://togows.org/api/ucsc/database/bigBed/chromosome:from-to/divisor/max
    • Coverage: http://togows.org/api/ucsc/database/bigBed/chromosome:from-to/divisor/coverage
• DNA sequence (2bit file)
  • Forward strand: http://togows.org/api/ucsc/database/chromosome:from-to[.fasta]
  • Reverse strand: http://togows.org/api/ucsc/database/chromosome:to-from[.fasta]
• Examples

  % curl http://togows.org/api/ucsc/
  % curl http://togows.org/api/ucsc/hg38/
  % curl http://togows.org/api/ucsc/hg38/refGene/
  % curl http://togows.org/api/ucsc/hg38/refGene/1,10
  % curl http://togows.org/api/ucsc/hg38/refGene/11,10.json
  % curl http://togows.org/api/ucsc/hg38/refGene/name2=UVSSA
  % curl http://togows.org/api/ucsc/hg38/refGene/chrom=chr13/1,10
  % curl http://togows.org/api/ucsc/hg38/omim2gene/geneId!=0/1,100
  % curl http://togows.org/api/ucsc/hg19/snp138/chrom=chr22;refUCSC=A;alleleFreqCount!=0/1,10.json
  % curl http://togows.org/api/ucsc/hg19/snp138/chr1:20,000-21,000.json
  % curl http://togows.org/api/ucsc/hg38/refGene/chr4:1,350,000-1,400,000
  % curl http://togows.org/api/ucsc/hg38/refGene/inclusive/chr4:1,350,000-1,400,000
  % curl http://togows.org/api/ucsc/hg38/refGene/exclusive/chr4:1,350,000-1,400,000
  % curl http://togows.org/api/ucsc/hg19/wgEncodeBroadHistoneGm12878H3k27acStdSig/info
  % curl http://togows.org/api/ucsc/hg19/wgEncodeBroadHistoneGm12878H3k27acStdSig/chr1:1000000-2000000/50 | spark
  ▁▁▁▁▂▁▁▁▃▂▃▂▃▁▁▃▃▄▁▁▂▁▃▁▁▄▂▃▁▃▅▆▃▆▁█▁▁▃▂▁▃▁▁▁▄▂▁▁▁
  % curl http://togows.org/api/ucsc/hg38/chr1:12,345-12,500.fasta
  >hg38:chr1:12,345-12,500
  TCAGACCAGCCGGCTGGAGGGAGGGGCTCAGCAGGTCTGGCTTTGGCCCTGGGAGAGCAG
  GTGGAAGATCAGGCAGGCCATCGCTGCCACAGAACCCAGTGGATTGGCCTAGGTGGGATC
  TCTGAGCTCAACAAGCCCTCTCTGGGTGGTAGGTGC
  

Note

TogoWS web site http://togows.org/ has an alias at http://togows.dbcls.jp/ where the original version of this service had launched in 2008.