- Docs
- Search and match the catalog
Search and match the catalog
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 |
| 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 "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 -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"]
}'
{
"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 -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.
Resolve a shared link
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 -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 -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.