{"id":16557684,"url":"https://github.com/patrickkfkan/genius-fetch","last_synced_at":"2025-10-16T15:28:17.567Z","repository":{"id":57686481,"uuid":"474343066","full_name":"patrickkfkan/genius-fetch","owner":"patrickkfkan","description":null,"archived":false,"fork":false,"pushed_at":"2023-07-23T21:45:11.000Z","size":71,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-17T12:47:36.014Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrickkfkan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-26T12:37:36.000Z","updated_at":"2023-07-23T21:42:57.000Z","dependencies_parsed_at":"2022-09-14T07:11:49.897Z","dependency_job_id":null,"html_url":"https://github.com/patrickkfkan/genius-fetch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fgenius-fetch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fgenius-fetch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fgenius-fetch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrickkfkan%2Fgenius-fetch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrickkfkan","download_url":"https://codeload.github.com/patrickkfkan/genius-fetch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241940529,"owners_count":20045878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T20:08:14.414Z","updated_at":"2025-10-16T15:28:12.520Z","avatar_url":"https://github.com/patrickkfkan.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# genius-fetch\n\nFetch data from [Genius](https://genius.com/) . Requires a Genius Access Token for certain functions.\n\n# Installation\n\n```\nnpm i genius-fetch --save\n```\n\n# Initialization\n\n```\n// ESM\nimport Genius from 'genius-fetch';\n// CJS\nconst Genius = require('genius-fetch');\n\nconst client = new Genius({\n  // Config options go here\n});\n\n\n// You can change or set a config option after initialization. E.g:\n\nclient.config({\n  accessToken: ...\n  debug: true\n  ...\n});\n```\n\n| **Config option**  | **Description**                                                                                                                                                              |\n|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| accessToken        | Genius Access Token. Certain  API calls require this to be provided.                                                                                                         |\n| rateLimiterEnabled | Whether to rate limit network requests. Default: `true`.                                                                                                                        |\n| 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). \u003cbr\u003e\u003c/br\u003eDefault: ```{ maxConcurrent: 5,   minTime: 100 }```|\n| cacheEnabled       | Whether to cache network responses. Default: `true`.                                                                                                                            |\n| cacheTTL           | The time-to-live of cache entries (seconds). Default: 3600.                                                                                                                   |\n| maxCacheEntries    | The maximum number of cache entries. Once reached, older entries will be removed. Default: 200.                                                                               |\n| debug              | Whether to log debug messages to the console. Default: `false`.                                                                                                                 |\n\n# Usage\n\n```\nconst matchParams = {\n  name: 'Evermore',\n  artist: 'Taylor Swift',\n};\nconst options = {\n  textFormat: TextFormat.Plain,\n  obtainFullInfo: true\n};\nreturn client.getSongsByBestMatch(matchParams, options).then((result) =\u003e {\n  // Do something with result\n});\n```\n\n# API\n\nEach function returns a Promise that resolves to the fetched data.\n\n## Fetching by ID\n\n### `getSongById(id, options)`\n### `getAlbumById(id, options)`\n### `getArtistById(id, options)`\n\nFetches a resource by ID. Requires Genius Access Token.\n\n\n| Option     | Description                                                    |\n|------------|----------------------------------------------------------------|\n| textFormat | Formatting to apply, where applicable: `TextFormat.HTML`, `TextFormat.Plain` or `TextFormat.DOM`. Default: `TextFormat.HTML`. |\n| raw        | Whether to return raw data. Default: `false`.                   |\n\nReturns 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)).\n\n## Fetching by Name\n\n### `getSongsByName(name, options)`\n### `getAlbumsByName(name, options)`\n### `getArtistsByName(name, options)`\n\nFetches resources matching `name`. Genius Access Token required if `obtainFullInfo` is set to `true` in `options`.\n\n| Option         | Description                                                                                                                                                                                                                                                    |\n|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| limit          | The number of results to return (max: 50). Default: 10.                                                                                                                                                                                                        |\n| offset         | The offset from which to return results. Default: 0 (i.e. return from first record).                                                                                                                                                                           |\n| obtainFullInfo | Whether to fetch full info for each result by calling `get\u003cSong/Album/Artist\u003eById()`. 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`. |\n| textFormat     | Formatting to apply, where applicable: `TextFormat.HTML`, `TextFormat.Plain` or `TextFormat.DOM`. Default: `TextFormat.HTML`.                                                                                                                                                                              |\n| raw            | Whether to return raw data. Default `false`.                                                                                                                                                                                                                   |\n\nReturns a Promise that resolves to an object with the following properties:\n\n| **Property** | **Description**                                         |\n|--------------|---------------------------------------------------------|\n| q            | The name searched.                                      |\n| 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)). |\n| limit        | The number of results requested.                        |\n| offset       | The offset from which results are returned.             |\n\n## Fetching by Best Match\n\n### `getSongsByBestMatch(matchParams, options)`\n\nReturns 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`.\n\nThis function performs matching on a \"best attempt\" basis, and does not guarantee that the results returned will fully match the values specified in `matchParams`.\n\n| Match Param | Description                            |\n|-------------|----------------------------------------|\n| name        | *Required*. The name of the song.      |\n| artist      | Artist                                 |\n| album       | Album                                  |\n\nYou **must** specify `name` and *at least* one of `artist` and `album` in `matchParams`.\n\n| Option         | Description                                                                                                                                                                                                                                                    |\n|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| limit          | The number of results to return (max: 50). Default: 10.                                                                                                                                                                                                        |\n| 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.                                                                                                                                                                           |\n| textFormat     | Formatting to apply, where applicable: `TextFormat.HTML`, `TextFormat.Plain` or `TextFormat.DOM`. Default: `TextFormat.HTML`.                                                                                                                                                                              |\n| 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`. |\n\n*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.\n\n### `getSongByBestMatch(matchParams, options)`\n\nConvenience function that calls `getSongsByBestMatch()` and returns the first result (or `null` if no result is found).\n\n### `getAlbumsByBestMatch(matchParams, options)`\n\nReturns 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`.\n\nThis function performs matching on a \"best attempt\" basis, and does not guarantee that the results returned will fully match the values specified in `matchParams`.\n\n| Match Param  | Description                            |\n|--------------|----------------------------------------|\n| name         | *Required*. The name of the album.     |\n| artist       | Artist                                 |\n| releaseYear  | Year of release.                       |\n| releaseMonth | Month of release.                      |\n| releaseDay   | Day of release.                        |\n\nYou **must** specify `name` and *at least* one of the other parameters in `matchParams`.\n\n| Option         | Description                                                                                                                                                                                                                                                    |\n|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| limit          | The number of results to return (max: 50). Default: 10.                                                                                                                                                                                                        |\n| 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.                                                                                                                                                                           |\n| textFormat     | Formatting to apply, where applicable: `TextFormat.HTML`, `TextFormat.Plain` or `TextFormat.DOM`. Default: `TextFormat.HTML`.                                                                                                                                                                              |\n| 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`. |\n\n*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.\n\n### `getAlbumByBestMatch(matchParams, options)`\n\nConvenience function that calls `getAlbumsByBestMatch()` and returns the first result (or `null` if no result is found).\n\n## Util Functions\n\n### `parseSongEmbed(embedValue)`\n\nParses the contents of the embed link contained in a song resource's `embed` property.\n\nReturns a Promise that resolves to an object with the following properties:\n\n| **Property** | **Description**                                                    |\n|--------------|--------------------------------------------------------------------|\n| linkElements | Array of \\\u003clink\\\u003e elements found in the embed content.               |\n| contentParts | Array of HTML elements comprising the 'body' of the embed content. |\n\n# Running the Examples\n\nFirst, provide your Genius Access Token in `./examples/accessToken.ts`.\n\nThen:\n\n```\n$ npm run example \u003cname of example script (without .ts file extension)\u003e\n```\n\nE.g.\n```\n$ npm run example getSongsByName\n```\n\n# Changelog\n\n1.0.0\n- Migrate to TypeScript\n- Package as ESM + CJS hybrid module\n\n0.1.0\n- Initial release\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickkfkan%2Fgenius-fetch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrickkfkan%2Fgenius-fetch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrickkfkan%2Fgenius-fetch/lists"}