The current version of the All Things Umphrey's API version is v2.

All valid requests to the API will begin with https://allthings.umphreys.com/api/v2. If you use that URL without any further data, it will return HTTP 204, no valid method found.

Methods

• setlists - display setlist data
• latest - display most recent show setlist data
• shows - display show data
• songs - display song data
• venues - display venue data
• jamcharts - display jam chart data
• albums - display data related to discography
• metadata - display setlist metadata

API Request Structure

• all data returned via a method: /[version]/[method].[format]
• specific row in a method: /[version]/[method]/[ID].[format]
• all rows matching a query: /[version]/[method]/[column]/[value].[format]

Authentication

Authentication is performed via API keys. API keys are private and only issued upon a justified request.

Additional Parameters

Additional parameters may be passed via query string:

• order_by: name of column to sort by
• direction: direction to sort, either asc or desc (default asc)
• limit: number, maximum number of results to return

e.g., /[version]/[method]/[column]/[value].[format]?order_by=[column]&direction=[direction]

Formats

API version 2 data is available in the following formats: JSON (.json) and HTML (.html).

Examples

The following are valid URLs to call the API:

Description	URL
https://allthings.umphreys.com/api/v2/setlists/showyear/2004.json?order_by=showdate	shows from 2004
https://allthings.umphreys.com/api/v2/setlists/songname/Anchor+Drops.html	setlist records of the song "Anchor Drops"
https://allthings.umphreys.com/api/v2/latest.json?order_by=position&direction=asc	latest shows, sorted by position ASC
https://allthings.umphreys.com/api/v2/shows/show_id/1341727440.html	shows with show_id 1341727440
https://allthings.umphreys.com/api/v2/venues.json	all venues
https://allthings.umphreys.com/api/v2/metadata/song_slug/chapter-6.html	metadata related to the song "Chapter 6"
https://allthings.umphreys.com/api/v2/shows/venuename/The+Opera+House+at+Expo+Gardens.html	venues named The Opera House at Expo Gardens
https://allthings.umphreys.com/api/v2/venues/state/IL.html	Shows in the state of Illinois
https://allthings.umphreys.com/api/v2/venues/city/Peoria.json	Shows in Peoria
https://allthings.umphreys.com/api/v2/jamcharts/city/Peoria.html	Jamchart entries in Peoria
https://allthings.umphreys.com/api/v2/jamcharts.html	All jamchart entries in JSON
https://allthings.umphreys.com/api/v2/albums.json	All album tracks in JSON

Error Checking

If your request contains an error, you may end up with unexpected output. If your request URI contains a typos, uses improper case, or requests or sorts by a nonexistent column, you may end up with no data in your response.

If you use the HTML format – an error will display "No results found.".

The JSON format works a bit differently. Every JSON response is has three return nodes: error, error_message, and data. A successful response will contain error 0, a blank error_message, and a data object populated with your response. An error response will contain error 1, a text-based error message, and a blank data object.