genius-fetch

genius-fetch

Fetch data from Genius . Requires a Genius Access Token for certain functions.

Installation

npm i genius-fetch --save

Initialization

// ESM
import Genius from 'genius-fetch';
// CJS
const Genius = require('genius-fetch');

const client = new Genius({
  // Config options go here
});


// You can change or set a config option after initialization. E.g:

client.config({
  accessToken: ...
  debug: true
  ...
});

Config option	Description
accessToken	Genius Access Token. Certain API calls require this to be provided.
rateLimiterEnabled	Whether to rate limit network requests. Default: true.
rateLimiterOptions	Options passed to the rate limiter, which is just a wrapper around Bottleneck and thus takes the same Bottleneck settings. Default: { maxConcurrent: 5, minTime: 100 }
cacheEnabled	Whether to cache network responses. Default: true.
cacheTTL	The time-to-live of cache entries (seconds). Default: 3600.
maxCacheEntries	The maximum number of cache entries. Once reached, older entries will be removed. Default: 200.
debug	Whether to log debug messages to the console. Default: false.

Usage

const matchParams = {
  name: 'Evermore',
  artist: 'Taylor Swift',
};
const options = {
  textFormat: TextFormat.Plain,
  obtainFullInfo: true
};
return client.getSongsByBestMatch(matchParams, options).then((result) => {
  // Do something with result
});

API

Each function returns a Promise that resolves to the fetched data.

Fetching by ID

getSongById(id, options)

getAlbumById(id, options)

getArtistById(id, options)

Fetches a resource by ID. Requires Genius Access Token.

Option	Description
textFormat	Formatting to apply, where applicable: TextFormat.HTML, TextFormat.Plain or TextFormat.DOM. Default: TextFormat.HTML.
raw	Whether to return raw data. Default: false.

Returns a Promise that resolves to an object representing the requested resource (i.e., Song, Album or Artist).

Fetching by Name

getSongsByName(name, options)

getAlbumsByName(name, options)

getArtistsByName(name, options)

Fetches resources matching name. Genius Access Token required if obtainFullInfo is set to true in options.

Option	Description
limit	The number of results to return (max: 50). Default: 10.
offset	The offset from which to return results. Default: 0 (i.e. return from first record).
obtainFullInfo	Whether to fetch full info for each result by calling get<Song/Album/Artist>ById(). If false, only snippet info will be returned. If true, you should make sure you have configured the library with the accessToken config option. Default: false.
textFormat	Formatting to apply, where applicable: TextFormat.HTML, TextFormat.Plain or TextFormat.DOM. Default: TextFormat.HTML.
raw	Whether to return raw data. Default false.

Returns a Promise that resolves to an object with the following properties:

Property	Description
q	The name searched.
items	An array of objects representing the fetched resources (i.e., Song, Album or Artist).
limit	The number of results requested.
offset	The offset from which results are returned.

Fetching by Best Match

getSongsByBestMatch(matchParams, options)

Returns an array of songs that best matches the criteria specified by matchParams, ordered by relevance. Requires Genius Access Token if album is specified in matchParams, or obtainFullInfo is set to true in options.

This function performs matching on a "best attempt" basis, and does not guarantee that the results returned will fully match the values specified in matchParams.

Match Param	Description
name	Required. The name of the song.
artist	Artist
album	Album

You must specify name and at least one of artist and album in matchParams.

Option	Description
limit	The number of results to return (max: 50). Default: 10.
sampleSize	The number of songs to fetch for best-matching. If it is smaller than limit, it will automatically be set to the same value as limit. Default: 20.
textFormat	Formatting to apply, where applicable: TextFormat.HTML, TextFormat.Plain or TextFormat.DOM. Default: TextFormat.HTML.
obtainFullInfo*	Whether to fetch full info for each result by calling getSongById(). If false, only snippet info will be returned. If true, you should make sure you have configured the library with the accessToken config option. Default: false.

*If album is specified in matchParams, then obtainFullInfo will be overridden with true. This is because the best-match logic requires full info to be obtained.

getSongByBestMatch(matchParams, options)

Convenience function that calls getSongsByBestMatch() and returns the first result (or null if no result is found).

getAlbumsByBestMatch(matchParams, options)

Returns an array of albums that best matches the criteria specified by matchParams, ordered by relevance. Requires Genius Access Token if releaseYear, releaseMonth or releaseDay is specified in matchParams, or obtainFullInfo is set to true in options.

This function performs matching on a "best attempt" basis, and does not guarantee that the results returned will fully match the values specified in matchParams.

Match Param	Description
name	Required. The name of the album.
artist	Artist
releaseYear	Year of release.
releaseMonth	Month of release.
releaseDay	Day of release.

You must specify name and at least one of the other parameters in matchParams.

Option	Description
limit	The number of results to return (max: 50). Default: 10.
sampleSize	The number of albums to fetch for best-matching. If it is smaller than limit, it will automatically be set to the same value as limit. Default: 20.
textFormat	Formatting to apply, where applicable: TextFormat.HTML, TextFormat.Plain or TextFormat.DOM. Default: TextFormat.HTML.
obtainFullInfo*	Whether to fetch full info for each result by calling getSongById(). If false, only snippet info will be returned. If true, you should make sure you have configured the library with the accessToken config option. Default: false.

*If releaseYear, releaseMonth or releaseDay is specified in matchParams, then obtainFullInfo will be overridden with true. This is because the best-match logic requires full info to be obtained.

getAlbumByBestMatch(matchParams, options)

Convenience function that calls getAlbumsByBestMatch() and returns the first result (or null if no result is found).

Util Functions

parseSongEmbed(embedValue)

Parses the contents of the embed link contained in a song resource's embed property.

Returns a Promise that resolves to an object with the following properties:

Property	Description
linkElements	Array of <link> elements found in the embed content.
contentParts	Array of HTML elements comprising the 'body' of the embed content.

Running the Examples

First, provide your Genius Access Token in ./examples/accessToken.ts.

Then:

$ npm run example <name of example script (without .ts file extension)>

E.g.

$ npm run example getSongsByName

Changelog

1.0.0

• Migrate to TypeScript
• Package as ESM + CJS hybrid module

0.1.0

• Initial release

License

MIT