bdacode / goear-api

This is a simple (NodeJS module) API to search music in GoEar.com

goear_api

Simple API to goear service. This is a humble attemp to create an easy to use API for consuming GoEar music info.

Getting Started

Install the module with: npm install goear_api

var api = require('goear_api');

api.search("The Police - Bring on the night", function(err, data) {
	console.log("Total songs available: " + data.totalCount);
	console.log("First title available: " + data.tracks[0].title);
});

Documentation

There is only one methods in this API:

search(searchTerm, options, callback)

This method sends a request to the service in order to search for provided terms.
Provided callback is called when results are available.
Due to the nature of the provider, chances are that the request can't be completed in a reasonable amount of time (example: You search for 100 songs of Michael Jackson with a minimum quality of 320kbps). In that case, the api will return the songs it had time to get.

Arguments:

• searchTerm {String} (required): The text we want to search
• options {Object} (optional): Search options
  • resultsCount (Number - default: 10): Number of results we want the function to return.
  • offset (Number - default: 1): Used when paginating to tell the function which pag we need.
  • minQuality (Number - default: 0): Used to filter songs with poor quality (Songs will have a quality equals or greater than this one).
  • timeout (Number - default: 15000): Milliseconds until api should stop searching.
• callback {Function} (required): Function to be called when results are available. The callback will have two params
  • error {Error}: If there is any error while searching
  • data {Object}: An object with the results. It has two params
    • totalCount {Number}: Total songs available for current search. This attribute will not exist if you filter your search by minQuality as the service provider is not able to return that info in a reasonable amount of time.
    • tracks: {Array}: Songs found. Each element is an object with these params:
      • id {String}: Song identifier
      • title {String}: Song title
      • quality {Number}: Quality (bitrate) of this song
      • duration {String}: Songs length with this format (MM:ss)
      • artist {String}: Song's artist name
      • link {String}: URL to the mp3 file for this song

Examples:

var api = require('goear_api');

// Basic search
api.search("Vetusta Morla", function(error, data) {
	console.log("Total songs available: " + data.totalCount);
	console.log("Returned songs: " + data.tracks.length): // Should be 10
	console.log("First title available: " + data.tracks[0].title);
});

// Search for a song expecting 25 results with a quality equal or greater than 256kbs
api.search("The Police - Bring on the night", {
	resultsCount: 25,
	minQuality: 256
}, function(error, data) {
	console.log("First title available: " + data.tracks[0].title);
});

License

Copyright (c) 2012 PaquitoSoft
Licensed under the MIT license.