8edff70d53e7dfe812ccb5c95a452fb2f4831716
hiram
Fri Apr 19 10:22:32 2019 -0700
adding the jsonOutputArrays option refs #18869
diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html
index 2efd0ef..239d3f1 100755
--- src/hg/htdocs/goldenPath/help/api.html
+++ src/hg/htdocs/goldenPath/help/api.html
@@ -1,204 +1,205 @@
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 ?
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 (use -1 to get maximum output)
- trackLeavesOnly=1 - on /list/tracks function, only show tracks, do not show composite container information
+- jsonOutputArrays=1 - on /getData/track function, JSON format is array type for each item of data, instead of the default object type
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 | trackLeavesOnly=1 |
|---|
| /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 |
|---|
+| /getData/track | ((hubUrl and genome) or db) and track | chrom, (start and end), maxItemsOutput, jsonOutputArrays |
|---|
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