The current version of the Slightly Stoopid Almanac API version is v2
.
All valid requests to the API will begin with https://stoopidheads.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
There is no authentication for API calls - no token or key is necessary. No data is passed via POST or HEAD requests, only by URI and, optionally, by GET parameters in the query string.
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://stoopidheads.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://stoopidheads.com/api/v2/list/country.json?artist=1&showyear=2025
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.