@giuband/pitchfork

An Unofficial Pitchfork Music API client for Node.js

Usage no npm install needed!

<script type="module">
  import giubandPitchfork from 'https://cdn.skypack.dev/@giuband/pitchfork';
</script>

README

Pitchfork Client

Travis CI

An unofficial Node.js client for Pitchfork reviews based on the Pitchfork API Client for Python.

Install

Using NPM

npm install pitchfork

Using Github

git clone git@github.com:omardelarosa/pitchfork-npm.git

You can then use it as a command-line tool or as a node module

API

You can require pitchfork and use it inside of any Node.JS application.

var p4k = require('pitchfork')

Search

A Search constructor that extends EventEmitter. Listeners can be attached to the 'ready' event which will fire when all reviews have been fetched and parsed. For example:


var p = require('pitchfork')
var s = new p.Search('wilco')

s.on('ready', function(results){
  console.log("results", results)
})

//=> [ {Review}, {Review}, {Review}, ... ]

.results

An Array of Review objects.

.init()

Called once when Search is instantiated to fetch results. Not usually called directly

Page

A Page constructor that extends EventEmitter. This constructor takes an integer argument specifying which page of reviews you wish to fetch from /reviews/albums/:page_num. Listeners can be attached to the 'ready' event which will fire when all reviews have been fetched and parsed. For example, this would return all the most recent reviews:


var p = require('pitchfork')
var s = new p.Page(1)

s.on('ready', function(results){
  console.log("results", results)
})

//=> [ {Review}, {Review}, {Review}, ... ]

Review

The Review constructor encapsulates methods and data relating to the Pitchfork review. The Review extends EventEmitter and fires a 'ready' event when the review has been fetched and parsed.

.attributes

An Object with information about the album and its text. Sample below:

{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "editorial": {
    "text": "...",
    "html": "..."
}

.fetch()

This method is automatically called when the Review is instantiated and returns a Promise. This generally isn't called directly.

.promise

This stores the thennable promise object generated by .fetch for attaching .then-style callbacks.

.verbose()

The full Review instance represented as JSON.

{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "editorial": {
    "html": " <p>Though Will Oldham began his musical career while in his early twenties, ... deep absorption or self-reflection so much as a kind of fond familiarity. </p> ",
    "text": " Though Will Oldham began his musical career while in his early twenties ... deep absorption or self-reflection so much as a kind of fond familiarity.  "
  }
}

.truncated()

The attributes of the Review instance with editorial.html/editorial.text condensed into the first 300 characters of of the text assigned to the key '.text'.

{
  "url": "/reviews/albums/9419-the-letting-go/",
  "name": "Bonnie \"Prince\" Billy - The Letting Go",
  "artist": "Bonnie \"Prince\" Billy",
  "album": "The Letting Go",
  "title": "Bonnie \"Prince\" Billy: The Letting Go | Album Reviews | Pitchfork",
  "label": "Palace / Drag City",
  "year": "2006",
  "score": 8.2,
  "cover": "http://cdn.pitchfork.com/albums/9255/homepage_large.e8a2bd20.jpg",
  "author": "Mark Richardson",
  "date": "September 18, 2006",
  "text": " Though Will Oldham began his musical career while in his early twenties, he's never exactly sounded young. From his first releases as Palace Music, Oldham's whiskey-soaked vocals and lyrical obsessions with death, sex, and religion have made \"maturity\" something of a non-issue. And yet, with his mo..."
}

.text_pretty_print()

Prints a plain-text representation of the review.


CLI (Command-Line Interface)

Returns a review for a given artist and album title.

$ pitchfork wilco 'yankee hotel foxtrot'
# { ... pretty-printed, colorized quasi-JSON object... }

or you can use -a and -t flags.

$ pitchfork -a wilco -t 'yankee hotel foxtrot'
# { ... pretty-printed, colorized quasi-JSON object... }

Returns a list of reviews for a given artist with no album.

$ pitchfork -a 'wilco'
# [ 
#    { ... pretty-printed, colorized quasi-JSON object... },
#    { ... pretty-printed, colorized quasi-JSON object... },
#    { ... pretty-printed, colorized quasi-JSON object... }
# ]

For valid, uncolored JSON, use the --json flag:

$ pitchfork -a 'wilco' -t 'yankee hotel foxtrot' --json
# { ... valid JSON object... }

Flags

flag(s) required argument description
-a y artist_name returns a review by given artist
-t album_title returns a review by given album title
-j,--json returns review attributes as un-prettified json
-v, --verbose returns review entire object as json
-V, --version returns version number
-T,--truncated returns a truncated json object of the review attributes
-tx,--text returns a text version of review (ex: to pipe output to 'less' )
-p page_number returns a list of reviews located on the specified page