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
• links - display links attached to shows
• uploads - display show metadata, including poster art and featured images
• appearances - display muscian appearances

Special Methods

Special methods behave differently than regular methods.

• list - the list method has a unique syntax and response format - see "List Syntax" for more

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:

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.

List Method Syntax

While most API methods are meant to return data, the “list” method is meant for applications to filter data. You can use the list method to filter by city, state, country, venue, day, month, or year. You can use this method to determine each city the band has played in, or each month in which the band has played.

The URL structure of a valid request looks like this: https://allthings.umphreys.com/api/v2/list/state.json (instead of state, you can use city, country, venue, day, month, or year).

There are two potential URL arguments for this method. If you pass artist=X the list method will return only show data associated with that artist. If you do not pass an artist argument, it will default to artist #1. By passing showyear=X, you can limit the results to a single year. A valid request might look like this: https://allthings.umphreys.com/api/v2/list/country.json?artist=1&showyear=2024

A list method response will always look like this:

{"error":0,"error_message":"","data":[{"field":"value1"},{"field":"value2"}...{"field":"valueX"}]}

The expectation is that your application will enumerate over the response.

Embeds

You can embed a setlist in a remote website via iframe or Javascript. In both cases, a URL is constructed like so: https://allthings.umphreys.com/api/embed/{arg}.html.

{arg} must be one of the following:

• a 10 digit integer corresponding to a show_id: https://allthings.umphreys.com/api/embed/1345147626.html
• a date in YYYYmmdd format: https://allthings.umphreys.com/api/embed/20020920.html
• a date in YYYY-mm-dd format https://allthings.umphreys.com/api/embed/2002-09-20.html

In all cases, the .html extension is optional. Here is example code for a valid embed:

<iframe src="https://allthings.umphreys.com/api/embed/2002-09-20.html"></iframe>

Another way would be to add the following in <script> tags. Since you won't want a full HTML document, make sure you add headless=1 to the URL:

const response = await fetch('https://allthings.umphreys.com/api/embed/2002-09-20.html?headless=1');
const body = await response.text();
document.querySelector('#some.selector').innerHTML = body;


or, using jQuery:

$('#some.selector').load('https://allthings.umphreys.com/api/embed/2002-09-20.html?headless=1');