kenjikatahira/ultimate-guitar-scraper

A scraper for http://ultimate-guitar.com

ultimate-guitar-scraper

A scraper for http://www.ultimate-guitar.com

Rock and roll! 🎸 🎶 🤘🏻

The scraper allow you to:

• Search TAB by song name and band name.
• Get TAB from its url.
• Get suggestions for artist or album.

installation

npm i ultimate-guitar-scraper --save

usage

search(query, callback [, requestOptions])

query

Type: Object

Name	Type	Require	Default
bandName	string	yes
songName	string	no
page	number	no	1
type	string or array	no	['tabs', 'chords']

Available TAB types:

• 'video lessons'
• 'tabs'
• 'chords'
• 'bass tabs'
• 'guitar pro tabs'
• 'power tabs'
• 'drum tabs'
• 'ukulele chords'

callback

Type: Function (error, tabs, requestResponse, requestBody)

• error: the error message. null if no error.
• tabs: array of TAB (see TAB structure below) null if error.
• requestResponse: the original response returned by request.
• requestBody: the original body returned by request.

requestOptions

Type: Object

Options of the HTTP request, made with package request.

examples

Basic usage.

var ugs = require('ultimate-guitar-scraper');
ugs.search({
  bandName: 'Pink Floyd',
  songName: 'Wish You Were Here',
  page: 1,
  type: ['tabs', 'chords', 'guitar pro tabs'],
}, function(error, tabs) {
  if (error) {
    console.log(error);
  } else {
    console.log(tabs);
  }
});

Using request options to pass a custom header.

var ugs = require('ultimate-guitar-scraper');

var query = {
  bandName: 'Half Moon Run'
};

var callback = function(error, tabs, response, body) {
  if (error) {
    console.log(error);
  } else {
    console.log(tabs);
    console.log('Utlimate Guitar server: ' + response.headers['server']);
  }
};

var options = {
  headers: {
    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36'
  }
};

ugs.search(query, callback, options);

tabs

An Array of TAB object that looks like this:

{
  artist: 'Pink Floyd',
  name: 'Wish You Were Here Live',
  difficulty: 'intermediate',       // can be null
  rating: 5,                        // can be null
  numberRates: 2,                   // can be null
  type: 'tab'
  url: 'http://tabs.ultimate-guitar.com/p/pink_floyd/wish_you_were_here_live_tab.htm'
}

get(tabUrl, callback [, requestOptions])

tabUrl

Type: String

The url of the TAB.

callback

Type: Function(error, tab, requestResponse, requestBody)

• error: the error message. null if no error.
• tab: the TAB (see TAB structure below) null if error.
• requestResponse: the original response returned by request.
• requestBody: the original body returned by request.

requestOptions

Type: Object

Options of the HTTP request, made with package request.

exemple

Basic usage.

var tabUrl = "https://tabs.ultimate-guitar.com/n/nirvana/smells_like_teen_spirit_ver2_crd.htm";
ugs.get(tabUrl, function(error, tab) {
  if (error) {
    console.log(error);
  } else {
    console.log(tab);
  }
});

tab

{
  name: 'Smells Like Teen Spirit',
  type: 'chords',
  artist: 'Nirvana',
  rating: 4,
  numberRates: 28,
  difficulty: null,
  contentText: '[Intro]\n\nFsus2  Bbsus2  Ab  Db (x4)\n\n\n[Verse Intro]\n\nFsus2  Bbsus2  Ab  Db (x2)\n\n\n...',
  contentHTML: '[Intro]\n\n<span>Fsus2</span>  <span>Bbsus2</span>  <span>Ab</span>  <span>Db</span> (x4)\n\n\n[Verse Intro]\n\n<span>Fsus2</span>  <span>Bbsus2...'
}

Content attributes depend on the type.

Type	Content attributes
tabs	contentText, contentHTML
chords	contentText, contentHTML
ukulele chords	contentText, contentHTML
drum tabs	contentText, contentHTML
bass tabs	contentText, contentHTML
guitar pro tabs	downloadUrl
power tabs	downloadUrl
video lessons	contentUrl

autocomplete(query, callback [, requestOptions])

query

Type: Object

Name	Type	Require	Default
query	string	yes
artist	string	only if type is 'tab'
type	string	no	'artist'

Available types:

• 'artist'
• 'tab'

callback

Type: Function(error, suggestions, requestResponse, requestBody)

• error: the error message. null if no error.
• suggestions: array of String that represent 'song' or 'artist'.
• requestResponse: the original response returned by request.
• requestBody: the original body returned by request.

requestOptions

Type: Object

Options of the HTTP request, made with package request.

examples

Searching for an 'artist'.

var ugs = require('ultimate-guitar-scraper');
ugs.autocomplete({
  query: 'Ozzy',
  type: 'artist'
}, function(error, suggestions) {
  if (error) {
    console.log(error);
  } else {
    console.log(suggestions);
  }
});

Searching for a 'song'.

var ugs = require('ultimate-guitar-scraper');
ugs.autocomplete({
  query: 'Crazy',
  artist: 'Ozzy Osbourne',
  type: 'tab'
}, function(error, suggestions) {
  if (error) {
    console.log(error);
  } else {
    console.log(suggestions);
  }
});

test

Feature tests are run daily, thank to Travis CI new feature CRON Jobs. This way we know if the scraper is ever broken.

Run the test:

npm test

contributing

Contribution is welcome! Open an issue first.

license

MIT.