API Documentation


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 all setlist data
  • latest - display most recent show setlist data
  • shows - display all show data
  • songs - display all song data
  • venues - display all venue data
  • jamcharts - display all jam chart data
  • albums - display all data related to discography

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/2001.json?order_by=showdate shows from 2001
https://allthings.umphreys.com/api/v2/setlists/songname/White+Man%27s+Moccasins.html setlist records of the song "White Man's Moccasins"
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/1334086329.html shows with show_id 1334086329
https://allthings.umphreys.com/api/v2/venues.json all venues
https://allthings.umphreys.com/api/v2/shows/venuename/Peabody%26%2339%3Bs.html venues named Peabody's
https://allthings.umphreys.com/api/v2/venues/state/OH.html Shows in the state of Ohio
https://allthings.umphreys.com/api/v2/venues/city/Cleveland.json Shows in Cleveland
https://allthings.umphreys.com/api/v2/jamcharts/city/Cleveland.html Jamchart entries in Cleveland
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.


Powered by Songfish