9662dcb8b56ccc906aa0d2a2b92f4ed0be5e0217 gperez2 Thu Jul 13 11:57:07 2023 -0700 Adding documentation and examples for hgSearch API, refs #24113 diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html index 5f76c3f..863a067 100755 --- src/hg/htdocs/goldenPath/help/api.html +++ src/hg/htdocs/goldenPath/help/api.html @@ -8,30 +8,31 @@ <h1>REST API data interface</h1> <h2>Contents</h2> <h6><a href="#REST">What is REST?</a></h6> <h6><a href="#Intro">What is JSON output data?</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="#Error_examples">Error return examples</a></h6> <h6><a href="#Practical_examples">Practical examples</a></h6> <!-- ========== What is REST? ============================== --> <a id="REST"></a> <h2>What is REST?</h2> <p> REST is an acronym for REpresentational State Transfer. It states architectural guidelines for how an API will operate. See also: <a target="_blank" href="https://restfulapi.net/">Principles of REST</a> </p> <!-- ========== What is JSON data? ============================== --> <a id="Intro"></a> <h2>What is JSON output data?</h2> @@ -59,115 +60,128 @@ <p> The following data sets can be accessed at this time: <ul> <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> </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> <p> <ul> <li><b>/list/publicHubs</b> - list public hubs</li> <li><b>/list/ucscGenomes</b> - list UCSC Genome Browser database genomes</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> </ul> </p> <!-- ========== Parameters to endpoint functions ======================= --> <a id="Parameters"></a> <h2>Parameters to endpoint functions</h2> <p> <ul> <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</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> <li>start=<123> - specify start coordinate (0 relative) for data from track or sequence retrieval (start and end required together). See also: <a href='http://genome.ucsc.edu/blog/the-ucsc-genome-browser-coordinate-counting-systems/' target=_blank>UCSC browser coordinate counting systems</a></li> <li>end=<456> - specify end coordinate (1 relative) for data from track or sequence retrieval (start and end required together). See also: <a href='http://genome.ucsc.edu/blog/the-ucsc-genome-browser-coordinate-counting-systems/' target=_blank>UCSC browser coordinate counting systems</a></li> <li>maxItemsOutput=1000 - limit number of items to output, default: 1,000, maximum limit: 1,000,000 (use <em>-1</em> to get maximum output)</li> <li>trackLeavesOnly=1 - on <em>/list/tracks</em> function, only show tracks, do not show composite container information</li> <li>jsonOutputArrays=1 - on <em>/getData/track</em> function, JSON format is array type for each item of data, instead of the default object type</li> <li>format=text - on <em>/list/files</em> function, return plain text listing of download files instead of JSON format output (which includes more meta-data information). Text output contains less meta-data in comment lines prefixed by the '#' hash character.</li> +<li>search=<term>&genome=<name> - on <em>/search</em> function, specify term to be +search within a UCSC Genome Browser genome assembly</li> +<li>categories=helpDocs - on <em>/search?search=<term>&genome=<name></em> function, restrict the search +within the UCSC Genome Browser help documentation</li> +<li>categories=publicHubs - on <em>/search?search=<term>&genome=<name></em> function, restrict the search +within the UCSC Genome Browser Public Hubs</li> +<li>categories=trackDb - on <em>/search?search=<term>&genome=<name></em> function, restrict the search +within the track database (trackDb) settings</li> </ul> </p> <p> The parameters are added to the endpoint URL beginning with a question mark <b>?</b>, and multiple parameters are separated with the semi-colon <b>;</b>. For example: <pre> https://api.genome.ucsc.edu/getData/sequence?genome=hg38;chrom=chrM </pre> </p> <!-- ========== Required and optional parameters ======================= --> <a id="Parameter_use"></a> <h2>Required and optional parameters</h2> <p> <table> <tr><th>Endpoint function</th><th>Required</th><th>Optional</th></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/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 and end</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> </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. </p> <p> @@ -305,30 +319,50 @@ target=_blank>Get track data for specified track in a track hub</a> - <br><b>api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=ensGene</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=ensGene;chrom=chr1' target=_blank>Get track data for specified track and chromosome in a track hub</a> - <br><b>api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=ensGene;chrom=chr1</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=gc5Base;chrom=chr1;start=4321;end=5678' target=_blank>Wiggle track data for specified track, chromosome with start and end limits in an assembly hub genome</a> - <br><b>api.genome.ucsc.edu/getData/track?hubUrl=http://hgdownload.soe.ucsc.edu/hubs/mouseStrains/hub.txt;genome=CAST_EiJ;track=gc5Base;chrom=chr1;start=4321;end=5678</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100' target=_blank>Wiggle track data for specified track in a UCSC database genome</a> - <br><b>api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100</b></li> <li><a href='https://api.genome.ucsc.edu/getData/track?genome=galGal6;track=ncbiRefSeqOther;chrom=chr1;start=750000;end=55700000' target=_blank>bigBed data from a UCSC database, chrom and start,end limits</a> - <br><b>api.genome.ucsc.edu/getData/track?genome=galGal6;track=ncbiRefSeqOther;chrom=chr1;start=750000;end=55700000</b></li> </ol> +<a id="Search_examples"></a> +<h3>Search functions</h3> +<ol> +<li><a href='https://api.genome.ucsc.edu/search?search=brca1&genome=hg38' +target=_blank>Search matches within a UCSC Genome Browser genome assembly</a> - +<br><b>api.genome.ucsc.edu/search?search=brca1&genome=hg38</b></li> +<li><a href='https://api.genome.ucsc.edu/search?search=bigBed&genome=hg38&categories=helpDocs' +target=_blank>Search matches within a UCSC Genome Browser genome assembly and restrict the +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> <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.soe.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.soe.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>