3c3c42b1f7491b065fe19858f24d91fd93524fe5
hiram
Mon Apr 8 14:37:27 2019 -0700
added support for PSL types and remove reference to top-level explore tools refs #18869
diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html
index 65231a9..f566a89 100755
--- src/hg/htdocs/goldenPath/help/api.html
+++ src/hg/htdocs/goldenPath/help/api.html
@@ -1,209 +1,202 @@
JSON API data interface
Contents
What is JSON data ?
JSON data is a data transfer syntax from a data provider to a data consumer.
See also: JSON Introduction
What is the access URL ?
-The gateway html page to the interface is available at
-api-test.gi.ucsc.edu. This page can be used
-to explore track hubs, assembly hubs, and UCSC browser data resources.
-Example URL links for JSON output are provided on that page for track
-types that are currently supported for data output. Work is underway
-to provide access to additional data track types.
-
-
This access url: https://api-test.gi.ucsc.edu/ is used to access
the endpoint functions. For example:
wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
+
What type of data can be accessed ?
The following data sets can be accessed at this time:
- Listing of available public hubs
- Listing of available UCSC browser genome assemblies
- List genomes from a specified assembly or track hub
- List available data tracks from a specified hub or UCSC browser genome assembly (see also: track definition help)
- List of chromosomes contained in an assembly hub or UCSC browser genome assembly.
- List of chromosomes contained in a specific track of an assembly or track hub or UCSC browser genome assembly.
- Return DNA sequence from an assembly hub 2bit file, or UCSC genome browser assembly
- Return track data from a specified assembly or track hub or UCSC genome browser assembly
Endpoint functions to return data
Use the url: https://api-test.gi.ucsc.edu/ is access
the endpoint functions. For example:
wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
- /list/publicHubs - list public hubs
- /list/ucscGenomes - list UCSC database genomes
- /list/hubGenomes - list genomes from specified hub
- /list/tracks - list data tracks available in specified hub or database genome (see also: track definition help)
- /list/chromosomes - list chromosomes from a data track in specified hub or database genome
- /getData/sequence - return sequence from specified hub or database genome
- /getData/track - return data from specified track in hub or database genome
Parameters to endpoint functions
- hubUrl=<url> - specify track hub or assembly hub URL
- genome=<name> - specify genome assemby in track or assembly hub (only used with hubUrl)
- db=<ucscDb> - specify database (aka genome assembly) in UCSC genome browser (either hubUrl or db specified, not both)
- track=<trackName> - specify data track in hub or UCSC database genome assembly
- chrom=<chrN> - specify chromosome name for sequence or track data
- start=<123> - specify start coordinate (0 relative) for data from track or sequence retrieval (start and end required together)
- end=<456> - specify end coordinate (1 relative) for data from track or sequence retrieval (start and end required together)
- (see also: UCSC browser coordinate counting systems)
- maxItemsOutput=1000 - limit number of items to output, default: 1,000, maximum limit: 1,000,000
The parameters are added to the endpoint URL beginning with a
question mark ?, and multiple parameters are separated with
the semi-colon ;. For example:
https://api-test.gi.ucsc.edu/getData/sequence?db=ce11;chrom=chrM
Required and optional parameters
| Endpoint function | Required | Optional |
|---|
| /list/publicHubs | (none) | (none) |
|---|
| /list/ucscGenomes | (none) | (none) |
|---|
| /list/hubGenomes | hubUrl | (none) |
|---|
| /list/tracks | (hubUrl and genome) or db | (none) |
|---|
| /list/chromosomes | ((hubUrl and genome) or db) and track | (none) |
|---|
| /getData/sequence | ((hubUrl and genome) or db) and chrom | start and end |
|---|
| /getData/track | ((hubUrl and genome) or db) and track | chrom, (start and end), maxItemsOutput |
|---|
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.
When not an assembly or track hub, to access UCSC database assemblies,
the parameter db=<name> is required.
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.
Supported track types, at this time (April 2019), for getData functions
Example data access
Listing functions
- list public hubs - api.genome.ucsc.edu/list/publicHubs
- list UCSC database genomes - api.genome.ucsc.edu/list/ucscGenomes
- list genomes from specified hub - api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt
- list tracks from specified hub and genome - api.genome.ucsc.edu/list/tracks?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
- list tracks from UCSC database genome - api.genome.ucsc.edu/list/tracks?db=ce11
- list chromosomes from UCSC database genome - api.genome.ucsc.edu/list/chromosomes?db=ce11
- list chromosomes from specified track in UCSC database genome - api.genome.ucsc.edu/list/chromosomes?db=ce11;track=gold
- list chromosomes from assembly hub genome -
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1
- list chromosomes from specified track in assembly hub genome -
api.genome.ucsc.edu/list/chromosomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
getData functions
- Get DNA sequence from specified chromosome in UCSC database genome -
api.genome.ucsc.edu/getData/sequence?db=ce11;chrom=chrM
- Get DNA sequence from specified chromosome and start,end coordinates in UCSC database genome -
api.genome.ucsc.edu/getData/sequence?db=ce11;chrom=chrM;start=4321;end=5678
- Get DNA sequence from a track hub where 'genome' is a UCSC database -
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;chrom=chrM;start=4321;end=5678
- Get DNA sequence from specified chromosome and start,end coordinates in an assembly hub genome -
api.genome.ucsc.edu/getData/sequence?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;chrom=chrCp;start=4321;end=5678
- Get track data for specified track in UCSC database genome -
api.genome.ucsc.edu/getData/track?db=ce11;track=gold;maxItemsOutput=100
- Get track data for specified track and chromosome in UCSC database genome -
api.genome.ucsc.edu/getData/track?db=ce11;track=gold;chrom=chrM
- Get track data for specified track, chromosome and start,end coordinates in UCSC database genome -
api.genome.ucsc.edu/getData/track?db=ce11;track=gold;chrom=chrI;start=47000;end=48000
- Get track data for specified track in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_
- Get track data for specified track and chromosome in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp
- Get track data for specified track in a track hub -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved
- Get track data for specified track and chromosome in a track hub -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/GillBejerano/hub.txt;genome=hg19;track=ultraConserved;chrom=chr8
- Wiggle track data for specified track, chromosome with start and end limits in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrCp;start=4321;end=5678
- Wiggle track data for specified track in a UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100
- bigBed data from a UCSC database, chrom and start,end limits -
api.genome.ucsc.edu/getData/track?genome=galGal6;track=ncbiRefSeqOther;chrom=chr1;start=750000;end=55700000
Error return examples
- Request track data for non-existent chromosome in an assembly hub genome -
api.genome.ucsc.edu/getData/track?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt;genome=_araTha1;track=assembly_;chrom=chrI;start=43521;end=54321