https://github.com/omardelarosa/pitchfork-npm
An Unofficial Pitchfork Music API client for Node.js
https://github.com/omardelarosa/pitchfork-npm
cli javascript node pitchfork pitchfork-client scraper scrapers
Last synced: 6 months ago
JSON representation
An Unofficial Pitchfork Music API client for Node.js
- Host: GitHub
- URL: https://github.com/omardelarosa/pitchfork-npm
- Owner: omardelarosa
- Created: 2014-07-16T00:55:33.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2018-02-18T21:58:26.000Z (over 7 years ago)
- Last Synced: 2024-04-25T14:02:34.210Z (over 1 year ago)
- Topics: cli, javascript, node, pitchfork, pitchfork-client, scraper, scrapers
- Language: JavaScript
- Homepage: https://www.npmjs.org/package/pitchfork
- Size: 48.8 KB
- Stars: 49
- Watchers: 6
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
#Pitchfork Client
An unofficial Node.js client for [Pitchfork](http://pitchfork.com/) reviews based on the [Pitchfork API Client for Python](https://github.com/michalczaplinski/pitchfork).
## Install
### Using NPM
```bash
npm install pitchfork
```
### Using Github
```bash
git clone git@github.com:omardelarosa/pitchfork-npm.git
```
You can then use it as a [command-line tool](#cli-command-line-interface) or as a [node module](#api)
##API
You can require ``pitchfork`` and use it inside of any Node.JS application.
```javascript
var p4k = require('pitchfork')
```
### Search
A ``Search`` constructor that extends [EventEmitter](http://nodejs.org/api/events.html#events_class_events_eventemitter). Listeners can be attached to the 'ready' event which will fire when all reviews have been fetched and parsed. For example:
```javascript
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](http://nodejs.org/api/events.html#events_class_events_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:
```javascript
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:
```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": {
"text": "...",
"html": "..."
}
```
``.fetch()``
This method is automatically called when the ``Review`` is instantiated and returns a [Promise](https://github.com/kriskowal/q). 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.
```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": "
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.
",
"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'.
```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",
"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.
```bash
$ pitchfork wilco 'yankee hotel foxtrot'
# { ... pretty-printed, colorized quasi-JSON object... }
```
or you can use -a and -t flags.
```bash
$ 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.
```bash
$ 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:
```bash
$ 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