# genius-lyrics-api

> A JavaScript package for non-browser environments that leverages [Genius API](https://genius.com/developers) to find (and scrape) song lyrics and album covers.

Latest version **3.2.1** (published 2024-03-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install genius-lyrics-api
pnpm add genius-lyrics-api
yarn add genius-lyrics-api
bun add genius-lyrics-api
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.2.1 |
| Published | 2024-03-03 |
| First published | 2019-11-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 9.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 261 |
| Author | Faisal Arshed |
| Maintainers | farshed |
| Keywords | genius, lyrics, album-art, scraper, genius-lyrics, genius-album-art, genius-api, lyrics-scraper |

## Links

- npm: https://www.npmjs.com/package/genius-lyrics-api
- Repository: https://github.com/farshed/genius-lyrics-api
- Homepage: https://github.com/farshed/genius-lyrics-api#readme
- Issues: https://github.com/farshed/genius-lyrics-api/issues
- npm.io page: https://npm.io/package/genius-lyrics-api

## Dependencies (2)

- [axios](https://npm.io/package/axios.md) ^1.6.7
- [cheerio-without-node-native](https://npm.io/package/cheerio-without-node-native.md) 0.20.2

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 3.2.1 (latest) — 2024-03-03
- 3.2.0 — 2021-09-14
- 3.1.1 — 2021-09-06
- 3.1.0 — 2021-09-06
- 3.0.6 — 2021-01-17
- 3.0.5 — 2021-01-06
- 3.0.4 — 2020-12-31
- 3.0.3 — 2020-08-12
- 3.0.2 — 2020-06-28
- 3.0.1 — 2020-06-28
- 3.0.0 — 2020-06-10
- 2.0.3 — 2020-03-28
- 2.0.2 — 2020-03-17
- 2.0.1 — 2020-03-17
- 2.0.0 — 2020-03-15
- … 6 more at https://npm.io/package/genius-lyrics-api/versions

## README

# genius-lyrics-api [![npm version](https://img.shields.io/npm/v/genius-lyrics-api.svg?style=flat)](https://www.npmjs.com/package/genius-lyrics-api)

A JavaScript package for non-browser environments that leverages [Genius API](https://genius.com/developers) to find (and scrape) song lyrics and album covers.<br/>

## Installation

Install with npm

```js
npm install --save genius-lyrics-api
```

Or install with Yarn

```js
yarn add genius-lyrics-api
```

## Usage

[Get the Genius Developer Access Token](https://genius.com/developers)
<br>

```js
import { getLyrics, getSong } from 'genius-lyrics-api';
```

```js
const options = {
	apiKey: 'XXXXXXXXXXXXXXXXXXXXXXX',
	title: 'Posthumous Forgiveness',
	artist: 'Tame Impala',
	optimizeQuery: true
};

getLyrics(options).then((lyrics) => console.log(lyrics));

getSong(options).then((song) =>
	console.log(`${song.id} - ${song.title} - ${song.url} - ${song.albumArt} - ${song.lyrics}`)
);
```

<br>

## Types

```
type options {
	title: string;
	artist: string;
	apiKey: string;		// Genius developer access token
	optimizeQuery?: boolean; // (optional, default: false) If true, perform some cleanup to maximize the chance of finding a match
	authHeader?: boolean; // (optional, default: false) Whether to include auth header in the search request
}

```

🚨 If `title` or `artist` is unknown, pass an empty string.

```
type song {
	id: number;		// Genius song id
	title: string;          // Song title
	url: string;		// Genius webpage URL for the song
	lyrics: string;		// Song lyrics
	albumArt: string;	// URL of the album art image (jpg/png)
}

```

```
type searchResult {
	id: number;		// Genius song id
	url: string;		// Genius webpage URL for the song
	title: string;		// Song title
	albumArt: string;	// URL of the album art image (jpg/png)
}
```

## Methods

genius-lyrics-api exposes the following methods:

### `getLyrics(options | url)`

Accepts [options](#types) or the url to a Genius song. <br/>
Returns a promise that resolves to a string containing lyrics. Returns `null` if no lyrics are found.

### `getAlbumArt(options)`

Accepts an [options](#types) object. <br/>
Returns a promise that resolves to a url (string) to the song's album art. Returns `null` if no url is found.

### `getSong(options)`

Accepts an [options](#types) object. <br/>
Returns a promise that resolves to an object of type [song](#types). Returns `null` if song is not found.

### `searchSong(options)`

Accepts an [options](#types) object. <br/>
Returns a promise that resolves to an array of type [searchResult](#types). Returns `null` if no matches are found.

### `getSongById(id: (number | string), access_token: string)`

Accepts a valid Genius song ID. IDs can be found using the `searchSong` method. <br/>
Returns a promise that resolves to an object of type [song](#types).

---
_Source: https://npm.io/package/genius-lyrics-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._