Docs - Musicfetch

Getting started

To access the Musicfetch endpoints you’ll need a subscription. Head to the homepage and pick a plan. All plans start with a free 7 day trial.

Authorization

All the Musicfetch endpoints require an Access Token. Copy an access token from your Account page. You can create up to 5 access tokens at any one time. A token must be provided whenever you call the API.

curl https://api.musicfetch.io/isrc?isrc=USUG11901472&services=appleMusic \
  -H 'x-token: YOUR_TOKEN'

Access tokens are secret and should not be exposed to the browser, as someone could steal your token and make requests on you behalf.

Lookup a track by url

You can lookup any track when you have an existing platform/store “source link”. Musicfetch will first lookup the source track and then attempt to find matches across the 25+ other platforms. We merge all the matches found and return a normalized MusicfetchTrack object.

Endpoint

https://api.musicfetch.io/url

Parameters

url - The source URL/link for a track on a given store. We support the following source links: Amazon, Apple Music, AWA, Beatport, Deezer, iHeartRadio, Joox, KKBOX, NetEase, QQ Music, SoundCloud, Spotify, Tidal, Trebel, Yandex, , YouTube.
services - A comma separated list of services (MusicfetchService) you'd like Musicfetch to search.
[country] - A two letter ISO country-code that you'd like to receive local store links for. This is only relevant to services that have country-specific links (Amazon, Apple Music, AWA, FLO, Gaana, iHeartRadio, JioSaavn, Joox, KKBOX, NetEase, QQ Music, 7digital, Spotify, Tidal) all other services have global links.

Example

curl https://api.musicfetch.io/url?\
  url=https://open.spotify.com/track/12345&\
  services=appleMusic \
  -H 'x-musicfetch-token: YOUR_TOKEN'

Lookup a track by ISRC

If you have an ISRC code for a specific track you can use the /isrc endpoint to lookup that track. We first lookup the ISRC on Spotify and then search all other services for matching tracks. A normalized MusicfetchTrack is returned.

Endpoint

https://api.musicfetch.io/isrc

Parameters

isrc - The ISRC of the track to lookup.
services - A comma separated list of services (MusicfetchService) you'd like Musicfetch to search.
[country] - A two letter ISO country-code that you'd like to receive local store links for. This is only relevant to services that have country-specific links (Amazon, Apple Music, AWA, FLO, Gaana, iHeartRadio, JioSaavn, Joox, KKBOX, NetEase, QQ Music, 7digital, Spotify, Tidal) all other services have global links.

Example

curl https://api.musicfetch.io/isrc?\
  isrc=USUG11901472&\
  services=appleMusic,youtube,deezer \
  -H x-token: YOUR_TOKEN'

Lookup an album by url

You can lookup any album when you have an existing platform “source link”. Musicfetch will first lookup the source album and then attempt to find matches across the 25+ other platforms. We merge all the matches found and return a normalized MusicfetchAlbum object.

Endpoint

https://api.musicfetch.io/url

Parameters

url - The source URL/link for an album on a given store. We support the following source links: Amazon, Apple Music, AWA, Beatport, Deezer, iHeartRadio, Joox, KKBOX, NetEase, QQ Music, SoundCloud, Spotify, Tidal, Trebel, Yandex, , YouTube.
services - A comma separated list of services (MusicfetchService) you'd like Musicfetch to search.
[country] - A two letter ISO country-code that you'd like to receive local store links for. This is only relevant to services that have country-specific links (Amazon, Apple Music, AWA, FLO, Gaana, iHeartRadio, JioSaavn, Joox, KKBOX, NetEase, QQ Music, 7digital, Spotify, Tidal) all other services have global links.

Example

curl https://api.musicfetch.io/url?\
  url=https://open.spotify.com/album/12345&\
  services=appleMusic,youtube,amazon \
  -H 'x-musicfetch-token: YOUR_TOKEN'

JSON result

{
  result: MusicfetchAlbum;
  performance: MusicfetchPerformance
}

Lookup an album by UPC

If you have the UPC (Universal Product Code) for an album you can use the /upc endpoint. Musicfetch will first lookup the album by UPC on Spotify and then attempt to find matches across the 25+ other platforms. We merge all the matches found and return a normalized MusicfetchAlbum object.

Endpoint

https://api.musicfetch.io/upc

Parameters

upc - The UPC of the album to lookup (must be on Spotify).
services - A comma separated list of services (MusicfetchService) you'd like Musicfetch to search.
[country] - A two letter ISO country-code that you'd like to receive local store links for. This is only relevant to services that have country-specific links (Amazon, Apple Music, AWA, FLO, Gaana, iHeartRadio, JioSaavn, Joox, KKBOX, NetEase, QQ Music, 7digital, Spotify, Tidal) all other services have global links.

Example

curl https://api.musicfetch.io/upc?\
  upc=00602458185355&\
  services=appleMusic,youtube,amazon \
  -H 'x-musicfetch-token: YOUR_TOKEN'

JSON result

{
  result: MusicfetchAlbum;
  performance: MusicfetchPerformance
}

Lookup an artist by url

You can lookup any artist when you have an existing platform “source link”. Musicfetch will first lookup the source artist and then attempt to find matches across the 25+ other platforms. We merge all the matches found and return a normalized MusicfetchArtist object.

Endpoint

https://api.musicfetch.io/url

Parameters

url - The source URL/link for an artist on a given store. We support the following source links: Amazon, Apple Music, AWA, Beatport, Deezer, iHeartRadio, Joox, KKBOX, NetEase, QQ Music, SoundCloud, Spotify, Tidal, Trebel, Yandex, , YouTube.
services - A comma separated list of services (MusicfetchService) you'd like Musicfetch to search.
[country] - A two letter ISO country-code that you'd like to receive local store links for. This is only relevant to services that have country-specific links (Amazon, Apple Music, AWA, FLO, Gaana, iHeartRadio, JioSaavn, Joox, KKBOX, NetEase, QQ Music, 7digital, Spotify, Tidal) all other services have global links.

Example

curl https://api.musicfetch.io/url?\
  url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02&\
  services=spotify,youtube,appleMusic,soundcloud \
  -H 'x-musicfetch-token: YOUR_TOKEN'

JSON result

{
  result: MusicfetchArtist;
  performance: MusicfetchPerformance
}

Object reference

References to all objects exposed by the Musicfetch API.

`MusicfetchTrack`

{
  type: 'track';
  name: string;

  /**
   * The ISRC code that uniquely identifies this sound recording
   */
  isrc?: string;

  /**
   * The duration of the track in milliseconds
   */
  duration: number;

  /**
   * The record label name
   */
  label: number;

  /**
   * A legal string to display owner copyright message
   */
  copyright: number;

  /**
   * If the track has explicit lyrics
   */
  isExplicit: boolean;

  /**
   * Url to 30 second preview audio
   */
  previewUrl?: string;

  /**
   * The 'best' image we found for this track.
   */
  image: MusicfetchImage;

  /**
   * All the artists that feature on this track. The first
   * artist in the list is considered the 'main' artist.
   */
  artists: MusicfetchArtist[];

  /**
   * The albums that this track was found on. This could
   * be a mixture of singles/EPs and full albums.
   */
  albums: MusicfetchAlbum[];

  /**
   * A list of services that this track was found on.
   */
  services: {
    [serviceType: string]: {
      id: string;
      link: string;
    };
  };
}

`MusicfetchAlbum`

{
  type: 'album';

  /**
   * The name/title of the album
   */
  name: string;

  /**
   * The UPC code that uniquely identifies this product
   */
  upc?: string;

  /**
   * The total number of tracks on the album
   */
  totalTracks: number;

  /**
   * The date this album was released
   */
  releaseDate: string;

  /**
   * Url to 30 second preview audio
   */
  previewUrl?: string;

  /**
   * The 'best' image we found for this album.
   */
  image: MusicfetchImage;

  /**
   * All the artists that feature on this album. The first
   * artist in the list is considered the 'main' artist.
   */
  artists: MusicfetchArtist[];

  /**
   * The tracks that feature on this album
   * (see `withTracks` option)
   */
  tracks?: MusicfetchTrack[];

  /**
   * The record label name
   */
  label: number;

  /**
   * A legal string to display owner copyright message
   */
  copyright: number;

  /**
   * A list of services that this track was found on.
   */
  services: {
    [serviceType: string]: {
      id: string;
      link: string;
    };
  };
}

`MusicfetchArtist`

{
  type: 'artist';
  name: string;

  /**
   * The bio/description of the artist
   */
  description: string;


  /**
   * The 'best' image we found for this track.
   */
  image: MusicfetchImage;

  /**
   * All the artists that feature on this track. The first
   * artist in the list is considered the 'main' artist.
   */
  artists: MusicfetchArtist[];

  /**
   * The artist's discography
   */
  albums: MusicfetchAlbum[];

  /**
   * The artist's most recent youtube videos
   */
  videos: MusicfetchVideo[];

  /**
   * A list of services this artist was found on. This can include
   * social platforms if links are discovered during the search.
   */
  services: {
    [serviceType: string]: {
      id: string;
      link: string;
    };
  };
}

`MusicfetchService`

Each service Musicfetch supports has a unique key. When making a call to the musicfetch API you need to provide a comma separated list of services you'll like to query for matches.

'amazon'
 | 'amazonMusic'
 | 'anghami'
 | 'appleMusic'
 | 'audiomack'
 | 'audius'
 | 'awa'
 | 'bandcamp'
 | 'bandsintown'
 | 'beatport'
 | 'boomplay'
 | 'deezer'
 | 'discogs'
 | 'flo'
 | 'gaana'
 | 'genius'
 | 'iHeartRadio'
 | 'imdb'
 | 'instagram'
 | 'itunesStore'
 | 'jioSaavn'
 | 'joox'
 | 'kkbox'
 | 'lineMusic'
 | 'musicBrainz'
 | 'napster'
 | 'netease'
 | 'pandora'
 | 'qobuz'
 | 'qqMusic'
 | 'sevenDigital'
 | 'shazam'
 | 'snapchat'
 | 'songkick'
 | 'soundcloud'
 | 'spotify'
 | 'telmoreMusik'
 | 'threads'
 | 'ticketmaster'
 | 'tidal'
 | 'tiktok'
 | 'tiktokMusic'
 | 'trebel'
 | 'x'
 | 'wikipedia'
 | 'wynkMusic'
 | 'yandex'
 | 'youseeMusik'
 | 'youtube'
 | 'youtubeMusic'
 | 'youtubeShorts'

Musicfetch SDK

Musicfetch has a dedicated JS/TS library providing a type-safe interface to the Musicfetch API as well as brand assets to get your UI off the ground quickly.

npm install musicfetch

Usage

Once musicfetch is installed into your node.js/browser project you can import it like any other NPM package. Configure an instance with your token and then use it throughout your app.

import Musicfetch from 'musicfetch';

// initialize once
export const musicfetch = new Musicfetch({
  token: YOUR_TOKEN,
});

Then use it throughout your application

import { musicfetch } from './my-musicfetch'

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

Using brand assets

The musicfetch package comes bundled with all brand names, SVG icons and colors, making building a slick UI that bit faster. Icons come as React components, SVG strings or SVG files.

import brands from 'musicfetch/brands';

const BrandCard = (link) => {
  // resolve brand from a link or key (eg. 'spotify')
  const { name, Icon, color } = brands.resolve(link);

  return (
    <div style={{ background: color }}>
      <h2>{brand.name}</h2>
      <Icon size={32} />
    </div>
  );
};