JSON API data interface

Contents

What is JSON data ?

What is the access URL ?

What type of data can be accessed ?

Endpoint functions

Parameters to endpoint functions

Required and optional parameters

Supported track types

Example data access, list functions

Example data access, getData functions

Error return examples

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.genome.ucsc.edu/ is used to access the endpoint functions. For example:

    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.genome.ucsc.edu/ is used to access the endpoint functions. For example:

    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.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM

Required and optional parameters

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

• bed
• bigBed
• bigNarrowPeak
• bigWig
• genePred
• narrowPeak
• psl
• rmsk - repeat masker
• wig
• (Work is under way to support additional track types)

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

1. list public hubs - api.genome.ucsc.edu/list/publicHubs
2. list UCSC database genomes - api.genome.ucsc.edu/list/ucscGenomes
3. list genomes from specified hub - api.genome.ucsc.edu/list/hubGenomes?hubUrl=http://genome-test.gi.ucsc.edu/~hiram/hubs/Plants/hub.txt
4. 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
5. list tracks from UCSC database genome - api.genome.ucsc.edu/list/tracks?genome=ce11
6. list chromosomes from UCSC database genome - api.genome.ucsc.edu/list/chromosomes?genome=ce11
7. list chromosomes from specified track in UCSC database genome - api.genome.ucsc.edu/list/chromosomes?genome=ce11;track=gold
8. 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
9. 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

1. Get DNA sequence from specified chromosome in UCSC database genome -
   api.genome.ucsc.edu/getData/sequence?genome=ce11;chrom=chrM
2. 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
3. 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
4. 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
5. Get track data for specified track in UCSC database genome -
   api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;maxItemsOutput=100
6. Get track data for specified track and chromosome in UCSC database genome -
   api.genome.ucsc.edu/getData/track?genome=ce11;track=gold;chrom=chrM
7. 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
8. 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
9. 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
10. 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
11. 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
12. 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
13. Wiggle track data for specified track in a UCSC database genome -
    api.genome.ucsc.edu/getData/track?genome=galGal6;track=gc5BaseBw;maxItemsOutput=100
14. 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

1. 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