https://github.com/readicculus/pysh
Phish.net API Python Wrapper for getting show, setlist, song, venue, and other phishy data
https://github.com/readicculus/pysh
api api-wrapper music-data phish phishnet python
Last synced: 2 months ago
JSON representation
Phish.net API Python Wrapper for getting show, setlist, song, venue, and other phishy data
- Host: GitHub
- URL: https://github.com/readicculus/pysh
- Owner: readicculus
- License: mit
- Created: 2024-05-01T19:33:41.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-03T20:34:07.000Z (about 2 years ago)
- Last Synced: 2026-02-19T02:07:28.888Z (4 months ago)
- Topics: api, api-wrapper, music-data, phish, phishnet, python
- Language: Python
- Homepage:
- Size: 34.2 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pysh - a phish.net API client in Python
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
Pysh is a Python wrapper for the [phish.net](phish.net) API that can be used to query for Phish songs,
setlists, shows, venues, and other phish related data. This project is not associated with phish.net and you must
follow their API's terms of service while using this project.
This wraps the API described in the [phish.net API v5 Docs](https://docs.phish.net/).
## Installation
This package is available on pypi [pysh-client](https://pypi.org/project/pysh-client/) and can be installed by running:
```bash
pip install pysh-client
```
## Requirements
#### API Key
You will need to setup an API key which requires you have a phish.net account.
This library gets the key from the `PHISH_API_KEY` environment variable.
Once you have your API key run the following before you can use this library.
```bash
export PHISH_API_KEY=xxx
```
You can alternatively pass the API key to the client when constructing it like this:
```python
from pysh import Client
c = Client(apikey="xxx")
```
## Usage
#### Filtering
There are a few ways to filter in your query calls. Filtering is optional.
1. You can filter by id, for example if trying to get a show by the show id you can specify `get_shows(id=123)`
2. OR, you can filter by a category and value, the category being one of the attributes in the schema of that method. For
example `get_shows(column='showyear', value='1995')` which returns all shows in 1995.
#### Additional Parameters
There are additional parameters you can define for all client methods defined by the `Parameters` class that allows you to
define the following optional parameters if desired:
1. `order_by`: name of column to sort by
2. `direction`: direction to sort, either asc or desc (default asc)
3. `limit`: number, maximum number of results to return
4. `no_header`: if requesting data in HTML format, the argument _noheader will suppress the Phish.net banner
5. `callback`: if requesting data in JSON format, sending a callback will wrap the resulting JSON file in a callback function call
```python
from pysh import Parameters, Client
c = Client()
c.get_shows(parameters=Parameters(order_by='showdate', direction='desc'))
```
You can read more about each of these parameters in the [Parameters Docs](https://docs.phish.net/#parameters)
## Examples
**Get all shows**
```python
c.get_shows()
```
**Get a Show by Year**
```python
c.get_shows(column="showyear", value="2020")
```
**Get a song by name**
```python
c.get_songs(column="slug", value="bug")
```
**Get a setlist for a show by date**
```python
c.get_setlists(column="showdate", value="1984-10-23")
```
## Client API Methods
Below are the currently available API methods usable via this client. I've not yet added the three
[special methods](https://docs.phish.net/special-methods) (attendance, reviews, and users) but will at some point.
Each pysh client method below corresponds to the phish.net api method and the return value is always a list
of dictionaries with the below dictionary schema.
#### Shows (v5/shows)
```
get_shows(...) ->
List[Dict{'showid', 'showyear', 'showmonth', 'showday', 'showdate', 'permalink', 'exclude_from_stats',
'venueid', 'setlist_notes', 'venue', 'city', 'state', 'country', 'artistid', 'artist_name',
'tourid', 'tour_name', 'created_at', 'updated_at'}]
```
#### Venues (v5/venues)
```
get_venues(...) ->
List[Dict{'venueid', 'venuename', 'city', 'state', 'country', 'venuenotes', 'alias', 'short_name'}]
```
#### Songs (v5/songs)
```
get_songs(...) ->
List[Dict{'songid', 'song', 'slug', 'abbr', 'artist', 'debut', 'last_played', 'times_played',
'last_permalink', 'debut_permalink', 'gap'}]
```
#### Songdata (v5/songdata)
```
get_songdata(...) ->
List[Dict{'songid', 'song', 'nickname', 'slug', 'lyrics', 'history', 'historian'}]
```
#### Setlists (v5/setlists)
```
get_setlists(...) ->
List[Dict{'showid', 'showdate', 'permalink', 'showyear', 'uniqueid', 'meta', 'reviews', 'exclude',
'setlistnotes', 'soundcheck', 'songid', 'position', 'transition', 'footnote', 'set', 'isjam',
'isreprise', 'isjamchart', 'jamchart_description', 'tracktime', 'gap', 'tourid', 'tourname',
'tourwhen', 'song', 'nickname', 'slug', 'is_original', 'venueid', 'venue', 'city', 'state',
'country', 'trans_mark', 'artistid', 'artist_slug', 'artist_name'}]
```
#### Artists (v5/artists)
```
get_artists(...) ->
List[Dict{'id', 'artist', 'slug'}]
```
#### Jamcharts (v5/jamcharts)
```
get_jamcharts(...) ->
List[Dict{'showid', 'showdate', 'permalink', 'showyear', 'uniqueid', 'meta', 'reviews', 'exclude',
'setlistnotes', 'soundcheck', 'songid', 'position', 'transition', 'footnote', 'set', 'isjam',
'isreprise', 'isjamchart', 'jamchart_description', 'tracktime', 'gap', 'tourid', 'tourname',
'tourwhen', 'song', 'nickname', 'slug', 'is_original', 'venueid', 'venue', 'city', 'state',
'country', 'trans_mark', 'artistid', 'artist_slug', 'artist_name'}]
```
---