Genomic data is considerably large, and computational biologists generally need all the data that is available for their analyses. Web APIs, as a technology, were designed for retrieving relatively small pieces of data, often from Javascript. Consequently, Web APIs may not be the best way to get data from the UCSC Genome Browser.
For this reason, we also provide alternative methods to access our data:
The URL https://api.genome.ucsc.edu/ is used to access the endpoint functions. For example:
curl -L 'https://api.genome.ucsc.edu/list/ucscGenomes'
@@ -141,30 +144,33 @@
The hubUrl and genome parameters are required together to specify a unique genome in an assembly or track hub. The genome for a track hub will usually be a UCSC database genome. Assembly hubs will have their own unique genome sequences. Specify genome without a hubUrl to refer to a UCSC Genome Browser assembly.
Using the chrom=<name> parameter will limit the request to the single specified chromosome. To limit the request to a specific position, both start=4321 and end=5678 must be given together. Using the revComp=1 parameter returns the reverse complement.
@@ -454,30 +462,100 @@ search within the UCSC Genome Browser help documentation -+ + +
+The /blat endpoint aligns one or more query sequences to the genome of an +assembly with BLAT and returns the alignments (hits) in PSL format. It uses the same BLAT +servers as the BLAT web page. +The type of query is given as the last part of the URL path: +
+| URL | Query sequence | Search |
|---|---|---|
| /blat/dna | DNA | DNA against the genome |
| /blat/protein | protein | protein against the genome, translated in all six frames |
| /blat/transRna | DNA or RNA | translated query against the translated genome, one strand of the query |
| /blat/transDna | DNA | translated query against the translated genome, both strands of the query |
| /blat/guess | DNA or protein | the type is guessed from the first sequence, like +"BLAT's guess" on the web page |
+The genome parameter names the assembly and userSeq holds the query sequence, either as +FASTA or as plain sequence. Use hubUrl together with genome to search an assembly hub. +The assembly must have a BLAT server. If it has none, the API returns an error. +
++API key: Unlike the other endpoints, /blat requires the URL parameter +apiKey. To get a key, log in to the Genome Browser and go to +My Data > My Track Hubs > Hub Development: API Key. Keys are specific to a server. +In addition, BLAT requests are slowed down more strongly than other API requests, per API key, +when they come in quickly, so a script should wait for each request to finish before it sends the next one. +
++Limits: A single query sequence can be at most 75,000 bases for DNA and 10,000 for protein or +translated queries. A request is limited to 25 sequences in total, and to 2.5 times the single +sequence limit for the sum of all sequences. Sequences that go over the limit are skipped. +
++Optional parameters: +
++For protein and translated queries, strand has two characters: the strand of the query followed +by the strand of the genome. +
++Example requests, with your own key in place of xxxxx (a DNA query, a protein query, +and a DNA query with the PSL text format): +
++curl -L 'https://api.genome.ucsc.edu/blat/dna?genome=hg38;apiKey=xxxxx;userSeq=GCCTTCGGGTCGGGAAGTCGAGCTCTGAGAAGTTCTCCTAGATTAG' +curl -L 'https://api.genome.ucsc.edu/blat/protein?genome=hg38;apiKey=xxxxx;userSeq=MEEPQSDPSVEPPLSQETFSDLWKLLPENNVLSPLPSQAMDDLMLSPDDIEQWFTEDPGP' +curl -L 'https://api.genome.ucsc.edu/blat/dna?genome=hg38;apiKey=xxxxx;format=psl;userSeq=GCCTTCGGGTCGGGAAGTCGAGCTCTGAGAAGTTCTCCTAGATTAG' ++