619d7563efb2f65ce421d9e40cb1965584ef1d78 max Sun Oct 4 05:51:58 2026 -0700 api.html: document the /blat endpoint (query types, apiKey, parameters, limits, output formats), refs #36315 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index adde9db564a..460b66ee614 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -9,30 +9,31 @@ <h2>Contents</h2> <h6><a href="#alternatives">Why you may not want to use this API</a></h6> <h6><a href="#REST">What are REST and JSON?</a></h6> <h6><a href="#Access">What is the access URL?</a></h6> <h6><a href="#Return">What type of data can be accessed?</a></h6> <h6><a href="#Endpoint">Endpoint functions</a></h6> <h6><a href="#Parameters">Parameters to endpoint functions</a></h6> <h6><a href="#Parameter_use">Required and optional parameters</a></h6> <h6><a href="#Track_types">Supported track types</a></h6> <h6><a href="#Mirrors">Using the API on mirrors and local installations</a></h6> <h6><a href="#list_examples">Example data access, list functions</a></h6> <h6><a href="#getData_examples">Example data access, getData functions</a></h6> <h6><a href="#Search_examples">Example data access, Search functions</a></h6> +<h6><a href="#blat_api">The /blat endpoint</a></h6> <h6><a href="#Error_examples">Error return examples</a></h6> <h6><a href="#Practical_examples">Practical examples</a></h6> <!-- ========== Do not use this API ============================== --> <h2 id='alternatives'>Why you may not want to use this API</h2> <p> 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.</p> <p> For this reason, we also provide alternative methods to access our data: <ul> <li> The <a href="https://genome.ucsc.edu/cgi-bin/hgTables" target="_blank">Table Browser</a> for @@ -110,30 +111,32 @@ <li>Find a genome in the UCSC browser with a search string</li> <li>List of available public hubs</li> <li>List of available UCSC Genome Browser genome assemblies</li> <li>List of files available for download for UCSC Browser genome assemblies</li> <li>List of genomes from a specified assembly or track hub</li> <li>List of available data tracks from a specified hub or UCSC Genome Browser genome assembly (see also: <a href='trackDb/trackDbHub.html' target=_blank>track definition help</a>)</li> <li>List of chromosomes contained in an assembly hub or UCSC Genome Browser genome assembly</li> <li>List of chromosomes contained in a specific track of an assembly or track hub, or UCSC Genome Browser genome assembly</li> <li>Return DNA sequence from an assembly hub 2bit file, or UCSC Genome Browser assembly</li> <li>Return track data from a specified assembly or track hub, or UCSC Genome Browser assembly</li> <li>Return search matches to words in track data, track names, track descriptions, public hub track names, and public hub descriptions within a UCSC Genome Browser genome assembly</li> +<li>Align a DNA or protein sequence to a genome with BLAT and return the hits in PSL format +(see <a href="#blat_api">The /blat endpoint</a>)</li> </ul> <b>Note:</b> BLAT also supports programmatic URL queries which return in JSON format. See our <a href="/FAQ/FAQblat.html#blat14">BLAT FAQ</a> for more info. </p> <!-- ========== Endpoint functions ======================= --> <a id="Endpoint"></a> <h2>Endpoint functions to return data</h2> <p> The URL <b>https://api.genome.ucsc.edu/</b> is used to access the endpoint functions. For example: <pre> curl -L 'https://api.genome.ucsc.edu/list/ucscGenomes' </pre> </p> @@ -141,30 +144,33 @@ <ul> <li><b>/findGenome</b> - search for a genome in the UCSC browser</li> <li><b>/list/publicHubs</b> - list public hubs</li> <li><b>/list/ucscGenomes</b> - list UCSC Genome Browser database genomes from database host</li> <li><b>/list/genarkGenomes</b> - list UCSC Genome Browser database genomes from assembly hub host</li> <li><b>/list/hubGenomes</b> - list genomes from specified hub</li> <li><b>/list/files</b> - list download files available for specified genome</li> <li><b>/list/tracks</b> - list data tracks available in specified hub or database genome (see also: <a href='trackDb/trackDbHub.html' target=_blank>track definition help</a>)</li> <li><b>/list/chromosomes</b> - list chromosomes from a data track in specified hub or database <li><b>/list/schema</b> - list the schema for a data track in specified hub or database genome</li> <li><b>/getData/sequence</b> - return sequence from specified hub or database genome</li> <li><b>/getData/track</b> - return data from specified track in hub or database genome</li> <li><b>/search</b> - return search matches within a UCSC Genome Browser genome assembly</li> +<li><b>/blat/dna</b>, <b>/blat/protein</b>, <b>/blat/transRna</b>, <b>/blat/transDna</b>, +<b>/blat/guess</b> - align a query sequence to a genome with BLAT. Requires an +<b>apiKey</b>, see <a href="#blat_api">The /blat endpoint</a></li> </ul> </p> <!-- ========== Parameters to endpoint functions ======================= --> <a id="Parameters"></a> <h2>Parameters to endpoint functions</h2> <p> <ul> <li>maxItemsOutput=1000000 - limit number of items to output, default: 1,000,000, maximum limit: 1,000,000 (use <em>-1</em> to get maximum output)</li> <li>hubUrl=<url> - specify track hub or assembly hub URL</li> <li>genome=<name> - specify genome assembly in UCSC Genome Browser or track/assembly hub. Use with /list/genarkGenomes to test for existence.</li> <li>track=<trackName> - specify data track in track/assembly hub or UCSC database genome assembly</li> <li>chrom=<chrN> - specify chromosome name for sequence or track data</li> @@ -217,30 +223,32 @@ <tr><th>Endpoint function</th><th>Required</th><th>Optional</th></tr> <tr><th>/findGenome</th><td>q</td><td>statsOnly, browser, year, category, status, level, maxItemsOutput</td></tr> <tr><th>/list/publicHubs</th><td>(none)</td><td>(none)</td></tr> <tr><th>/list/ucscGenomes</th><td>(none)</td><td>(none)</td></tr> <tr><th>/list/genarkGenomes</th><td>(none)</td><td>genome, maxItemsOutput</td></tr> <tr><th>/list/hubGenomes</th><td>hubUrl</td><td>(none)</td></tr> <tr><th>/list/files</th><td>genome</td><td>format=text, maxItemsOutput</td></tr> <tr><th>/list/tracks</th><td>genome or (hubUrl and genome)</td><td>trackLeavesOnly=1</td></tr> <tr><th>/list/chromosomes</th><td>genome or (hubUrl and genome)</td><td>track</td></tr> <tr><th>/list/schema</th><td>(genome or (hubUrl and genome)) and track</td><td>(none)</td></tr> <tr><th>/getData/sequence</th><td>(genome or (hubUrl and genome)) and chrom</td><td>start, end, revComp=1</td></tr> <tr><th>/getData/track</th><td>(genome or (hubUrl and genome)) and track</td><td>chrom, (start and end), maxItemsOutput, jsonOutputArrays</td></tr> <tr><th>/search</th><td>search and genome</td><td>categories=helpDocs, categories=publicHubs, categories=trackDb</td></tr> +<tr><th>/blat/<type></th><td>genome and userSeq and apiKey</td><td>hubUrl, format, +maxItemsOutput, jsonOutputArrays</td></tr> </table> </p> <p> The <b>hubUrl</b> and <b>genome</b> parameters are required together to specify a unique genome in an assembly or track hub. The <b>genome</b> for a track hub will usually be a UCSC database genome. Assembly hubs will have their own unique <b>genome</b> sequences. Specify <b>genome</b> without a <b>hubUrl</b> to refer to a UCSC Genome Browser assembly. </p> <p> Using the <b>chrom=<name></b> parameter will limit the request to the single specified chromosome. To limit the request to a specific position, both <b>start=4321</b> and <b>end=5678</b> must be given together. Using the <b>revComp=1</b> parameter returns the reverse complement. </p> @@ -454,30 +462,100 @@ search within the UCSC Genome Browser help documentation</a> - <br><b>api.genome.ucsc.edu/search?search=bigBed&genome=hg38&categories=helpDocs</b></li> <li><a href='https://api.genome.ucsc.edu/search?search=cerebellum&genome=hg38&categories=publicHubs' target=_blank>Search matches within a UCSC Genome Browser genome assembly and restrict the search within the UCSC Genome Browser Public Hubs</a> - <br><b>api.genome.ucsc.edu/search?search=cerebellum&genome=hg38&categories=publicHubs</b></li> <li><a href='https://api.genome.ucsc.edu/search?search=signal&genome=hg38&categories=trackDb' target=_blank>Search matches within a UCSC Genome Browser genome assembly and restrict the search within the track database (trackDb) settings</a> - <br><b>api.genome.ucsc.edu/search?search=signal&genome=hg38&categories=trackDb</b></li> </ol> <p> </p> +<!-- ========== BLAT ======================= --> +<a id="blat_api"></a> +<h2>The /blat endpoint</h2> +<p> +The <b>/blat</b> 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 <a href="../../cgi-bin/hgBlat" target=_blank>BLAT web page</a>. +The type of query is given as the last part of the URL path: +</p> +<table> +<tr><th>URL</th><th>Query sequence</th><th>Search</th></tr> +<tr><td>/blat/dna</td><td>DNA</td><td>DNA against the genome</td></tr> +<tr><td>/blat/protein</td><td>protein</td><td>protein against the genome, translated in all six frames</td></tr> +<tr><td>/blat/transRna</td><td>DNA or RNA</td><td>translated query against the translated genome, one strand of the query</td></tr> +<tr><td>/blat/transDna</td><td>DNA</td><td>translated query against the translated genome, both strands of the query</td></tr> +<tr><td>/blat/guess</td><td>DNA or protein</td><td>the type is guessed from the first sequence, like +"BLAT's guess" on the web page</td></tr> +</table> +<p> +The <b>genome</b> parameter names the assembly and <b>userSeq</b> holds the query sequence, either as +FASTA or as plain sequence. Use <b>hubUrl</b> together with <b>genome</b> to search an assembly hub. +The assembly must have a BLAT server. If it has none, the API returns an error. +</p> +<p> +<b>API key:</b> Unlike the other endpoints, <b>/blat</b> requires the URL parameter +<b>apiKey</b>. To get a key, log in to the Genome Browser and go to +<i>My Data > My Track Hubs > Hub Development: API Key</i>. 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. +</p> +<p> +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. +</p> +<p> +Optional parameters: +</p> +<ul> +<li><b>format</b> - the format of the result: + <ul> + <li>(not set) - JSON with the usual API fields (<b>genome</b>, <b>qType</b>, <b>tType</b>, + <b>itemsReturned</b>, etc.) and the hits as a list called <b>blat</b>. Each hit is an object with the named + PSL fields: <b>matches</b>, <b>misMatches</b>, <b>repMatches</b>, <b>nCount</b>, <b>qNumInsert</b>, + <b>qBaseInsert</b>, <b>tNumInsert</b>, <b>tBaseInsert</b>, <b>strand</b>, <b>qName</b>, + <b>qSize</b>, <b>qStart</b>, <b>qEnd</b>, <b>tName</b>, <b>tSize</b>, <b>tStart</b>, <b>tEnd</b>, + <b>blockCount</b>, <b>blockSizes</b>, <b>qStarts</b>, <b>tStarts</b>. + See the <a href="../../FAQ/FAQformat.html#format2" target=_blank>PSL format description</a>.</li> + <li><b>psl</b> or <b>text</b> - plain text PSL, with the PSL header lines</li> + <li><b>hgblat</b> - the JSON that <b>hgBlat?output=json</b> returns, with a + <b>fields</b> list and each hit as a list of values in the <b>blat</b> list</li> + </ul></li> +<li><b>jsonOutputArrays=1</b> - return each hit in the default JSON as a list of values instead of an +object, with the field names in a separate <b>fields</b> list, like <b>/getData/track</b> does.</li> +<li><b>maxItemsOutput</b> - the maximum number of hits to return</li> +</ul> +<p> +For protein and translated queries, <b>strand</b> has two characters: the strand of the query followed +by the strand of the genome. +</p> +<p> +Example requests, with your own key in place of <b>xxxxx</b> (a DNA query, a protein query, +and a DNA query with the PSL text format): +</p> +<pre> +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' +</pre> + <a id="Error_examples"></a> <h3>Error return examples</h3> <p> <ol> <li><a href='https://api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.gi.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=assembly;chrom=chrI;start=43521;end=54321' target=_blank>Request track data for non-existent chromosome in an assembly hub genome</a> - <br><b>api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.gi.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=assembly;chrom=chrI;start=43521;end=54321</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?genome=hg19;track=decipherSnvs' target=_blank>Request track data from a restricted track</a>. See <a href='../../FAQ/FAQdownloads.html#download40' target=_blank>FAQ</a> - <br><b>api.genome.ucsc.edu/getData/track?genome=hg19;track=decipherSnvs</b></li> </ol> </p> <!-- ========== Practical Examples ======================= -->