Docs
/
Search and match the catalog

Search and match the catalog

CoreGuide · 2 min

Search tracks, albums and artists across services, match items into other services, look up an ISRC on every store, resolve a shared link, read a public playlist, and embed a player. No connected user needed.

The catalog endpoints work on the public catalogs of the music services. They need no connected user, so they work before anyone signs in.

Task	Endpoint
Which services and types can I search?	GET/public/search/introspection
Find a track, album or artist on several services	POST/public/search
Find the same items on other services	POST/public/search/match
Find the track of an ISRC on every store	GET/public/isrc/{isrc}
What does this shared link point at?	POST/public/inspect/url
Read the tracks of a public playlist	POST/public/inspect/playlistItems
Embed a player for a link	POST/public/embed/url

Authentication

Use Authorization: Token <clientId>. The Client ID is public, so these calls may run in a browser or an app. Basic and DevToken work too. The embed endpoint needs no credential.

Which services

The catalog covers its own list of services, which differs from the list of services a user can connect. Ask for it:

curl

curl "https://api.musicapi.com/public/search/introspection" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID"

sources lists the values that sources, destinations and source take below. types lists track, album and artist.

Search across services

curl

curl -X POST "https://api.musicapi.com/public/search" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "track",
    "track": "Bezos I",
    "artist": "Bo Burnham",
    "album": "INSIDE",
    "sources": ["spotify", "appleMusic", "deezer"]
  }'

200 OK (one source shown)

{
  "tracks": [
    {
      "source": "spotify",
      "status": "success",
      "type": "track",
      "data": {
        "externalId": "5aszL9hl6SBzFNsOvw8u8w",
        "name": "Bezos I",
        "artistNames": ["Bo Burnham"],
        "albumName": "INSIDE",
        "imageUrl": "https://i.scdn.co/image/ab67616d0000b27388fed14b936c38007a302413",
        "previewUrl": null,
        "isrc": "",
        "duration": 58149,
        "url": "https://open.spotify.com/track/5aszL9hl6SBzFNsOvw8u8w"
      }
    }
  ]
}

Each source answers on its own, with its own status: success, not_found or error. One failing service does not fail the others.

Match items into other services

You have ids on one service and want the same items on others. Send the ids and the destinations:

curl

curl -X POST "https://api.musicapi.com/public/search/match" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "destinations": ["appleMusic", "tidal"],
    "objects": [{ "id": "5aszL9hl6SBzFNsOvw8u8w", "source": "spotify" }]
  }'

The answer has one entry per object: the object with its catalog data, and one match per destination that has it. Use the matched ids in the library writes of a user on that service.

Look up an ISRC

You have an ISRC, for example from a distributor, and want the track on the stores. Send the ISRC:

curl

curl "https://api.musicapi.com/public/isrc/USRC17607839?sources=deezer,boomplay" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID"

200 OK

{
  "isrc": "USRC17607839",
  "results": {
    "deezer": {
      "status": "found",
      "track": {
        "externalId": "2451377",
        "url": "https://www.deezer.com/track/2451377",
        "name": "Crazy Eyes",
        "artistNames": ["Daryl Hall & John Oates"],
        "albumName": "Bigger Than Both Of Us",
        "albumId": "241202",
        "duration": 187000,
        "isrc": "USRC17607839",
        "imageUrl": "https://cdn-images.dzcdn.net/images/cover/d5f6a0809403ac3f64f538d97e7a89a3/1000x1000-000000-80-0-0.jpg"
      }
    },
    "boomplay": { "status": "notFound", "track": null }
  }
}

The stores are Spotify, Apple Music, Deezer, Amazon Music and Boomplay: the stores that can search by ISRC. Leave sources out to ask all of them. Each store answers on its own: found, notFound or error (with error set to timeout or unavailable). The stores run in parallel, and a slow store answers timeout instead of holding the answer.

Only a track with the same ISRC counts, so a found track is the release itself, not a near match. A found track is cached for a day and a miss for an hour. A release that is not out yet answers notFound: ask again after a few hours. Each store you ask counts as one request on your usage.

Resolve a shared link

curl

curl -X POST "https://api.musicapi.com/public/inspect/url" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://tidal.com/browse/track/131696293"}'

The answer says what the link points at (a track, an album or a playlist), on which service, with its metadata.

Read a public playlist

curl

curl -X POST "https://api.musicapi.com/public/inspect/playlistItems" \
  -H "Authorization: Token $MUSICAPI_CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"serviceId": "spotify", "playlistId": "37i9dQZF1DXcBWIGoYBM5M"}'

Up to 50 tracks per page. Send the answer's nextParam back in the body for the next page, until it is null.

Embed a player

curl

curl -X POST "https://api.musicapi.com/public/embed/url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://open.spotify.com/track/0pqnGHJpmpxLKifKRmU6WP"}'

The answer holds embedCode (an iframe), embedUrl, the available sizes and the defaultSize. To change the height, set it in two places: the height of the iframe and the height query parameter of its src. See the embed player page for a live example.