https://github.com/patrickkfkan/genius-fetch
https://github.com/patrickkfkan/genius-fetch
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/patrickkfkan/genius-fetch
- Owner: patrickkfkan
- Created: 2022-03-26T12:37:36.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2023-07-23T21:45:11.000Z (almost 2 years ago)
- Last Synced: 2025-02-17T12:47:36.014Z (3 months ago)
- Language: TypeScript
- Size: 69.3 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# genius-fetch
Fetch data from [Genius](https://genius.com/) . 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](https://www.npmjs.com/package/bottleneck) and thus takes the same [Bottleneck settings](https://www.npmjs.com/package/bottleneck#docs).
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](./docs/api/interfaces/Song.md), [Album](./docs/api/interfaces/Album.md) or [Artist](./docs/api/interfaces/Artist.md)).
## 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 `getById()`. 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](./docs/api/interfaces/Song.md), [Album](./docs/api/interfaces/Album.md) or [Artist](./docs/api/interfaces/Artist.md)). |
| 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 \ 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
```
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