# Search and match the catalog
URL: https://musicapi.com/docs/catalog/overview.md

> Search tracks, albums and artists across services, match items into other services, resolve a shared link, read a public playlist, and embed a player. No connected user needed.

Product: MusicAPI Core. Section: 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`](https://musicapi.com/docs/reference/get-search-introspection.md)    |
| Find a track, album or artist on several services | [`POST /public/search`](https://musicapi.com/docs/reference/search-catalog.md)                           |
| Find the same items on other services             | [`POST /public/search/match`](https://musicapi.com/docs/reference/match-catalog-items.md)                |
| What does this shared link point at?              | [`POST /public/inspect/url`](https://musicapi.com/docs/reference/inspect-url.md)                         |
| Read the tracks of a public playlist              | [`POST /public/inspect/playlistItems`](https://musicapi.com/docs/reference/get-public-playlist-items.md) |
| Embed a player for a link                         | [`POST /public/embed/url`](https://musicapi.com/docs/reference/create-embed-player.md)                   |

## 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:

```bash
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

```bash
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"]
  }'
```

```json
{
  "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:

```bash
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](https://musicapi.com/docs/user-library/overview-and-pagination.md) of a user on that service.

## Resolve a shared link

```bash
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

```bash
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

```bash
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](https://musicapi.com/embed) for a live example.