Musicfetch

The type-safe JavaScript and TypeScript client for the Musicfetch API. Resolve music-service URLs and match tracks or albums by ISRC and UPC across Spotify, Apple Music, YouTube, Deezer, TIDAL, and other supported services.

Install

npm install musicfetch

yarn add musicfetch

Create a client

import { Musicfetch } from 'musicfetch';

const musicfetch = new Musicfetch({
  token: process.env.MUSICFETCH_TOKEN!,
});

The client uses https://api.musicfetch.io/ by default. You can provide a different endpoint or a custom fetch implementation in the constructor. Keep API tokens in server-side code and environment variables.

You can start a trial and create a token from Musicfetch pricing.

Look up a service URL

Use url() with a supported artist, album, or track URL:

const { result, errors } = await musicfetch.url({
  url: 'https://open.spotify.com/track/6habFhsOp2NvshLv26DqMb',
  services: ['appleMusic', 'deezer', 'youtube'],
});

if (result.type === 'track') {
  console.log(result.name);
  console.log(result.genres);
  console.log(result.services?.appleMusic?.link);
}

The result is a discriminated union with a type of artist, album, or track.

Look up a track by ISRC

const { result: track } = await musicfetch.isrc({
  isrc: 'USUG11901472',
  services: ['appleMusic', 'spotify', 'youtube'],
});

console.log(track.name);
console.log(track.services?.spotify?.link);

Look up an album by UPC

const { result: album } = await musicfetch.upc({
  upc: '00602537618132',
  services: ['appleMusic', 'spotify', 'youtube'],
  withTracks: true,
});

console.log(album.name);
console.log(album.tracks);

Open endpoint

open() calls the public Open URL endpoint. Its default return type is GetOpenUrlResult, and a custom response type can be supplied when needed.

const { result } = await musicfetch.open({
  url: 'https://open.spotify.com/track/6habFhsOp2NvshLv26DqMb',
  services: ['appleMusic', 'youtube'],
  country: 'US',
});

Lookup options

The lookup methods infer their return types from the requested options. Common options include:

| Option | Description | | --- | --- | | country | Country or territory used for localized store links. Defaults to US. | | withAllLinks | Return all localized links instead of only the requested country. | | withArtists | Include related artists where supported. | | withAlbums | Include related albums where supported. | | withTracks | Include album tracks where supported. | | withLyrics | Include track lyrics where supported. | | withCredits | Include track or album credits where supported. | | withServiceLevel | Include selected metadata inside each service result. | | fetchOptions | Add request headers or framework-specific fetch options. |

For example, service-level fields are reflected in the inferred result:

const { result } = await musicfetch.isrc({
  isrc: 'USUG11901472',
  services: ['appleMusic', 'spotify'],
  withServiceLevel: ['isrc', 'genres', 'credits'],
});

console.log(result.services?.spotify?.isrc);
console.log(result.services?.appleMusic?.genres);

Types and service helpers

The root package exports the client, lookup capability lists, and public result types:

import {
  Musicfetch,
  SERVICES_WITH_SEARCH,
  SERVICES_WITH_URL_LOOKUP,
  type MusicfetchAlbum,
  type MusicfetchArtist,
  type MusicfetchItem,
  type MusicfetchLookupResult,
  type MusicfetchServiceType,
  type MusicfetchTrack,
} from 'musicfetch';

SERVICES_WITH_URL_LOOKUP contains services accepted as source URLs. SERVICES_WITH_SEARCH contains services Musicfetch can search for matching results.

Brand assets

The musicfetch/brands export includes names, colors, URL patterns, and SVG icons:

import brands from 'musicfetch/brands';

const spotify = brands.resolve('spotify');
const fromUrl = brands.resolve('https://open.spotify.com/track/...');

console.log(spotify?.name);
console.log(fromUrl?.color);
console.log(brands.all);

Brands can also be imported directly:

import spotify from 'musicfetch/brands/spotify';
import spotifyIconUrl from 'musicfetch/brands/spotify/icon.svg';

React brand icons

Install React in your application, then render a bundled brand:

import brands from 'musicfetch/brands';
import { BrandIcon } from 'musicfetch/react';

const spotify = brands.resolve('spotify');

export const SpotifyIcon = () =>
  spotify ? <BrandIcon brand={spotify} size={32} /> : null;

BrandIcon accepts size, color, opacity, direction, className, style, and testId.

Package exports

| Import | Contents | | --- | --- | | musicfetch | API client, capability lists, and public TypeScript types | | musicfetch/brands | Brand collection and resolver | | musicfetch/brands/<service> | A single brand definition | | musicfetch/brands/<service>/icon.svg | A service SVG asset | | musicfetch/react | React BrandIcon component |

See the complete Musicfetch documentation for endpoint behavior, supported parameters, and interactive examples.