node-songkick

node-songkick

A node.js wrapper around songkick's API.

Installation

You can use npm to install this module:

npm install node-songkick

If you prefer to use the source form github, clone the repo:

git clone https://github.com/carvil/node-songkick.git

Usage

After installing/cloning the module, you can open a node console:

node

and require the module:

var Songkick = require("node-songkick");

If you cloned the repo, use this instead:

var Songkick = require("<PATH-TO-node-songkick>");

And create an instance of Songkick:

var sk = new Songkick("<YOUR API KEY>");

You can request an API key at songkick's website.

After creating an instance, it is possible to query information about artists. More to come in the future (venue, location, events)

Artist

All

Assuming there is a sk object, it is possible to search for all artists:

sk.artist.all({ page: 1 }, callback)

The params are:

• A hash of options: page and the api key;
• A callback function, which will handle the results.

An example:

> sk.artist.all({page: 1}, function(r) {console.log(r);})
> { resultsPage:
    { results: { artist: [Object] },
      page: 1,
      totalEntries: 266226,
      perPage: 30 } }

The results object will contain the first set of results. More examples in specs/fixtures.

Search

Assuming there is a sk object, it is possible to search for artists:

sk.artist.search("joe bonamassa", { page: 1, per_page: 25 }, callback)

The params are:

• The query string;
• A hash of options: per_page and page, besides the api key and query string already present;
• A callback function, which will handle the results.

An example:

> sk.artist.search("muse",{},function(r) { console.log(r); } )
> { resultsPage:
   { results: { artist: [Object] },
     totalEntries: 0,
     perPage: 50,
     page: 1,
     status: 'ok' } }

The results object will contain a number of results. More examples in specs/fixtures.

Calendar

Assuming there is a sk object, it is possible to search for an artist's calendar:

sk.artist.calendar("artist_id", 324967,{ per_page: 10, page: 1 }, callback )

The params are:

• The type of the id used: artist_id or music_brainz_id;
• The actual id;
• A hash of options: per_page and page, besides the api key and query string already present;
• A callback function, which will handle the results.

An example:

> sk.artist.calendar("artist_id", 324967, { per_page: 10 }, function(r) { console.log(r);} )
> { resultsPage:
   { results: { event: [Object] },
     totalEntries: 5,
     perPage: 10,
     page: 1,
     status: 'ok' } }

The results object will contain a number of results. More examples in specs/fixtures.

Gigography

Assuming there is a sk object, it is possible to search for an artist's gigography:

sk.artist.gigography("artist_id", 324967, { per_page: 5, page: 2 }, callback )

The params are:

• The type of the id used: artist_id or music_brainz_id;
• The actual id;
• A hash of options: per_page and page, besides the api key and query string already present;
• A callback function, which will handle the results.

An example:

> sk.artist.gigography("artist_id", 324967,{ per_page: 10, page: 2 }, function(r) { console.log(r);} )
> { resultsPage:
   { results: { event: [Object] },
     totalEntries: 961,
     perPage: 10,
     page: 2,
     status: 'ok' } }

The results object will contain a number of results. More examples in specs/fixtures.

Testing

In order to run the tests, clone the repo:

git clone https://github.com/carvil/node-songkick.git
cd node-songkick

Install dependencies:

npm install

And the run:

npm test

or

jasmine-node --coffee --verbose ./spec/

TODO

• Venues
• Events
• Metro areas
• Users

Submitting a Pull Request

• Fork the repository.
• Create a topic branch.
• Add specs for your unimplemented feature or bug fix.
• Run jasmine-node --coffee --verbose ./spec/. If your specs pass, return to step 3.
• Implement your feature or bug fix.
• Run jasmine-node --coffee --verbose ./spec/. If your specs fail, return to step 5.
• Add documentation for your feature or bug fix.
• Add, commit, and push your changes.
• Submit a pull request.

Supported node versions

I only tested this module on node 0.8.0, therefore I don't know if it will work on previous/more recent versions. Please let me know if you tried it and if it worked/didn't work.

Disclaimer

This was the first time I wrote a node module. If you find stuff that could be improved or done differently/in a better way, I would love to hear from you. Feel free to DM me on twitter or send me a pull request!

Copyright

Copyright (c) 2012 Carlos Vilhena. See LICENSE for details.