API Documentation

Phish.in provides a JSON API for programmatic access to content

Requests

All requests must be in the form of HTTP GET and must include the Accept: application/json header as well as a bearer auth header:Authorization: Bearer <your_api_key>

API keys can be requested via the contact page.

Responses

Responses will include the header Content-Type: application/json and should be parsed as JSON.

Responses to successful requests look like this:

{ "success": true, "total_entries": #, "total_pages": #, "page": #, "data": [response content] }

Responses to failed calls look like this:

{ success: false, message: "Something went wrong!" }

Parameters

Most routes accept the following optional parameters:

  • sort_attrWhich attribute to sort on (Ex: "date", "name")
  • sort_dirWhich direction to sort in (asc|desc)
  • per_pageHow many results to list per page (default: 20)
  • pageWhich page of results to display (default: 1)

A few routes also accept the following optional parameters:

  • tag[/tracks and /shows] Return only results that have the specified tag slug (Example: /shows?tag=sbd)

Endpoints

All endpoints can be reached by using the full address of https://phish.in/api/v1 followed by one of these routes:GET /erasReturns all Eras and the Years that belong to eachGET /eras/:eraReturns Years contained within the specified EraGET /yearsReturns a list of all Years.
Add ?include_show_counts=true for a more detailed response.GET /years/:yearReturns a list of Shows (basic data) for the given YearGET /songsReturns a list of all SongsGET /songs/:id
GET /songs/:slugReturns Song metadata for given ID (or slug) as well as a list of Tracks that contain performances of the Song.
Tracks may be sorted by date or duration.GET /toursReturns a list of all ToursGET /tours/:id
GET /tours/:slugReturns Tour metadata for given ID (or slug) as well as a list of Shows that occurred within the TourGET /venuesReturns a list of all VenuesGET /venues/:id
GET /venues/:slugReturns Venue metadata for given ID (or slug) as well as a list of Shows (ids, dates) that occurred at the VenueGET /showsReturns a list of all ShowsGET /shows/:idGET /shows/:date (yyyy-mm-dd)Returns Show metadata for given ID or date (eg '1994-10-31') as well as Venue metadata and a list of Tracks belonging to the ShowGET /show-on-date/:dateReturns Show metadata for given date as well as Venue metadata and a list of Tracks belonging to the ShowGET /shows-on-day-of-year/:dayReturns Show metadata for given day (eg 'october-31' or '10-31') as well as Venue metadata and a list of Tracks belonging to each ShowGET /random-showReturns metadata for a randomly selected Show as well as Venue metadata and a list of Tracks belonging to the ShowGET /tracksReturns a list of all TracksGET /tracks/:idReturns Track metadata for given IDGET /search/:termReturns search results based on term grouped by entity.GET /playlists/:slugReturns Playlist metadata for given slug and a list of Tracks belonging to the PlaylistGET /tagsReturns a list of all TagsGET /tags/:idGET /tags/:slugReturns show and track associations for given ID or slug

Examples

Requesting "the song with ID of 40":

GET https://phish.in/api/v1/songs/40.json

will result in this response:

{ "success": true, "total_entries": 1, "total_pages": 1, "page": 1, "data": { "id": 40, "title": "Any Colour You Like", "alias": null, "tracks_count": 1, "slug": "any-colour-you-like", "updated_at": "2012-08-25T15:04:00Z", "tracks": [ { "id": 17963, "title": "Any Colour You Like", "duration": 211696, "show_id": 904, "show_date": "1998-11-02", "set": "2", "position": 20, "likes_count": 0, "slug": "any-colour-you-like", "mp3": "https://phish.in/audio/000/017/963/17963.mp3" } ] } }

Requesting "the 3 most recent shows":

GET https://phish.in/api/v1/shows.json?per_page=3&page=1&sort_attr=date&sort_dir=desc

will result in a response that looks like this:

{ "success": true, "total_entries": 1467, "total_pages": 489, "page": 1, "data": [ { "id": 1846, "date": "2016-01-02", "duration": 9825384, "incomplete": false, "tour_id": 96, "venue_id": 408, "likes_count": 14, "taper_notes": "2016- 01/02: Madison Square Garden; New York, NY **24bit** (mk41v)\n\nPhish\nMadison Square Garden; New York, NY\n01/02/15\n\nLocation: OTS DFC\nSource: Schoeps mk41v> NBob KCY> Naiant PFA> Tascam DR70d @ 24 bit / 48 kHz\nTransfer: SD Card> Macbook Pro> Sound Studio> Tracking and Fades> Izotope (Resample & Dither)> xact> Flaccing\n\nRecorded and transferred by Noah Bickart \n\nSet I:\nYour Pet Cat (4:57)\nAC/DC Bag (6:55)\nNICU (6:11)\nIt's Ice (8:09)\nHorn (3:48)\nDivided Sky (16:23)\nAxilla I (3:26)\nMaze (9:27)\nTrain Song (3:07)\nJulius (8:30)\n\nSet II: \nTweezer (22:07)\nSand (9:41)\nLimb By Limb (7:23)\nSuzy Greenberg (5:49)\nHarry Hood (11:48)\nYou Enjoy Myself \n\nEncore Break\nThe Lizards (10:05)\nTweezer Reprise (4:34)\n", "updated_at": "2016-01-03T20:25:45Z", "venue_name": "Madison Square Garden", "location": "New York, NY" }, { "id": 1845, "date": "2016-01-01", "duration": 9844247, "incomplete": false, "tour_id": 96, "venue_id": 408, "likes_count": 8, "taper_notes": "Phish\n1/1/16\nMadison Square Garden\nNew York, NY \n\n\nField: AKG C414xls card/hyper > Edirol R4Pro ( Oade preamp mod ) @ 24/88.2\nconfig: pointed at PA array, behind SBD, dead center, 13 feet high\n\nPath: R4Pro > WaveBurner ( track on sector boundaries, fades, SRC, BDC ) > xACT ( to flac, and for tagging and checksums )\n\nRecorded, processed and let loose by Mike Kutik ( padelimike at mac d0t c0m )\nAt bt.etree.org 2016-01-02\n\n\nSet the First:\ncrowd in\nStealing Time From The Faulty Plan\nHeavy Things\nHow Many People Are You?\nStash\nUndermind\nRift\nWingsuit\nOcelot\nLawn Boy\nRun Like An Antelope\n\n\nSet the Second:\ncrowd in\nDown With Disease \nDirt\nHalfway To The Moon \nTheme From The Bottom \nLight \nFuego \nSlave To The Traffic Light\nencore break\nFarmhouse\nexit music\n\n\nFade tracks are included for smooth CDR burning.", "updated_at": "2016-01-02T18:56:44Z", "venue_name": "Madison Square Garden", "location": "New York, NY" }, { "id": 1844, "date": "2015-12-31", "duration": 12891297, "incomplete": false, "tour_id": 96, "venue_id": 408, "likes_count": 22, "taper_notes": "2015- 12/31: Madison Square Garden; New York, NY **24bit** (mk41v)\n\nPhish\nMadison Square Garden; New York, NY\n12/31/15\n\nLocation: OTS DFC\nSource: Schoeps mk41v> NBob KCY> Naiant PFA> Tascam DR70d @ 24 bit / 48 kHz\nTransfer: SD Card> Macbook Pro> Sound Studio> Tracking and Fades> Izotope (Resample & Dither)> xact> Flaccing\n\nRecorded and transferred by Noah Bickart \n\nSET ONE:\n\nThe Moma Dance\nPossum\nWolfman's Brother\nBirds of a Feather\nI Didn't Know> Happy Birthday\nMartian Monster\nReba\nWalls Of The Cave\n\nSET TWO:\n\nIntro\nThe Wedge\nWilson\nA Song I Heard The Ocean Sing\nYarmouth Road\nKill Devil Falls\nPiper\nTwist\n\nSET THREE:\n\nNo Men In No Man's Land> Auld Lang Syne\nBlaze On\nCarini\nDavid Bowie\nThe Horse> Silent In The Morning\nBackwards Down the Number Line\n\nEncore Break\n\nTube\nCavern", "updated_at": "2016-01-01T18:24:38Z", "venue_name": "Madison Square Garden", "location": "New York, NY" } ] }