daab58830afaaff9af3cd658fc0c544b2f151e7f
hiram
Tue May 7 10:55:03 2019 -0700
update to api.genome.ucsc.edu reference refs #18869
diff --git src/hg/htdocs/goldenPath/help/api.html src/hg/htdocs/goldenPath/help/api.html
index 2f7f451..5111363 100755
--- src/hg/htdocs/goldenPath/help/api.html
+++ src/hg/htdocs/goldenPath/help/api.html
@@ -1,264 +1,271 @@
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
+This access url: https://api.genome.ucsc.edu/ is used to access
the endpoint functions. For example:
- wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
+ wget -O- 'https://api.genome.ucsc.edu/list/publicHubs'
What type of data can be accessed ?
The following data sets can be accessed at this time:
- List of available public hubs
- List of available UCSC Genome Browser genome assemblies
- List genomes from a specified assembly or track hub
- List available data tracks from a specified hub or UCSC Genome Browser genome assembly
(see also: track definition help)
- List of chromosomes contained in an assembly hub or UCSC Genome Browser genome assembly
- List of chromosomes contained in a specific track of an assembly or track hub, or UCSC Genome
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
-The url https://api-test.gi.ucsc.edu/ is used to access
+The url https://api.genome.ucsc.edu/ is used to access
the endpoint functions. For example:
- wget -O- 'https://api-test.gi.ucsc.edu/list/publicHubs'
+ wget -O- 'https://api.genome.ucsc.edu/list/publicHubs'
- /list/publicHubs - list public hubs
- /list/ucscGenomes - list UCSC Genome Browser 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 assembly in UCSC Genome Browser or track/assembly hub
- track=<trackName> - specify data track in track/assembly 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). See also: UCSC browser coordinate counting systems
- 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?genome=ce11;chrom=chrM
+https://api.genome.ucsc.edu/getData/sequence?genome=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 | genome or (hubUrl and genome) | trackLeavesOnly=1 |
|---|
| /list/chromosomes | genome or (hubUrl and genome) | track |
|---|
| /getData/sequence | (genome or (hubUrl and genome)) and chrom | start and
end |
|---|
| /getData/track | (genome or (hubUrl and genome)) 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. 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.
Any extra parameters not allowed in a function will be flagged as an error.
Supported track types, at this time (April 2019), for getData functions
Example data access
+
+Your WEB browser can be configured to interpret JSON data and format
+in a convenient browsing format. Firefox has this function built in,
+other browsers have add-ons that can be turned on to format JSON data.
+With your browser thus configured, the following links can demonstrate
+the functions of the API interface.
+
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?genome=ce11
- list chromosomes from UCSC database genome -
api.genome.ucsc.edu/list/chromosomes?genome=ce11
- list chromosomes from specified track in UCSC database genome -
api.genome.ucsc.edu/list/chromosomes?genome=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?genome=ce11;chrom=chrM
- Get DNA sequence from specified chromosome and start,end coordinates in UCSC database genome -
api.genome.ucsc.edu/getData/sequence?genome=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?genome=ce11;track=gold;maxItemsOutput=100
- Get track data for specified track and chromosome in UCSC database genome -
api.genome.ucsc.edu/getData/track?genome=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?genome=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