---
title: "Provider metadata blocks (Apple Music, Spotify, Deezer, MusicBrainz)"
description: "How to request Apple Music, Spotify, Deezer, and MusicBrainz metadata on an AudD match, where each block's fields are documented, and when song_link is enough instead."
slug: "/resources/reference/provider-metadata"
section: "reference"
keywords: [audd, spotify metadata, apple music metadata, deezer, musicbrainz, provider metadata]
---

# Provider metadata blocks (Apple Music, Spotify, Deezer, MusicBrainz)

When AudD recognizes a song you can ask it to attach metadata from up to
four external providers — Apple Music, Spotify, Deezer, and
MusicBrainz — to the match. Each block mirrors that provider's own
track/album object, so you get a direct service URL, audio preview,
artwork, and the provider's own IDs without making a second call. The
providers carry different fields, so each block is documented on its own
page; this page covers what's common — how to request them, the shared
mechanics, and when `song_link` is enough instead.

## The blocks

| Block | Shape | Reference |
|---|---|---|
| Apple Music | object | [Apple Music metadata block](/resources/reference/apple-music) |
| Spotify | object | [Spotify metadata block](/resources/reference/spotify) |
| Deezer | object | [Deezer metadata block](/resources/reference/deezer) |
| MusicBrainz | array of recordings | [MusicBrainz metadata block](/resources/reference/musicbrainz) |

Napster metadata is [no longer available](/resources/reference/napster):
the platform ceased operations and `napster` was removed from the API
(sending it adds warning #51).

Each per-provider page documents that block's typed fields, how to read the
ones developers actually use, and where to look up the provider's complete
schema.

## Requesting metadata blocks

On the HTTP API, list the providers you want in the `return` form field as
a comma-separated string:

```bash
curl https://api.audd.io/ \
  -F api_token=your-api-token \
  -F url=https://audd.tech/example.mp3 \
  -F return=apple_music,spotify,deezer,musicbrainz
```

In the SDKs, the option is named `returnMetadata` (or the language's
idiomatic equivalent — `return_metadata` in Python). `return` is the raw
API name; `return_metadata`/`returnMetadata` is the SDK name for the same
thing.

```python
from audd import AudD

audd = AudD("your-api-token")  # dashboard.audd.io
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music", "spotify", "musicbrainz"],
)
```

```ts
import { AudD } from "@audd/sdk";

const audd = new AudD({ apiToken: "your-api-token" }); // dashboard.audd.io
const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["apple_music", "spotify", "musicbrainz"],
});
```

Each block is read as the typed property on the result — `result.spotify`,
`result.apple_music`, and so on (`result.spotify` in Node), with attribute
access on the typed sub-fields. Fields beyond the typed surface round-trip
through Pydantic's `model_extra` (Python) / `extras` (Node). The
per-provider pages show the access pattern for each block.

Three things to know before you request everything:

- **Each provider you request adds latency.** AudD looks the track up in
  each service you ask for. Request only the providers you will actually
  read.
- **A block is `null` or absent when you didn't request it** (or when the
  provider has no match for that recording). The presence of `apple_music`
  is not guaranteed even when you ask — handle the missing case, and treat
  every sub-field as possibly absent or null too.
- **Provider metadata is not available on the enterprise endpoint.** It is
  a standard-endpoint feature. On enterprise matches, use `song_link`
  (below) to reach the services.

The `market` parameter sets the country code used for the Apple Music and
Spotify lookups (defaults to `us`); it changes which catalog entry and
which `available_markets` you get back. It does not affect the other blocks.

## The simpler alternative: `song_link`

You don't need a provider block just to send a user to a streaming service.
Every match — standard or enterprise, with no `return` requested — carries
a `song_link`: a universal lis.tn URL such as `https://lis.tn/NbkVb` that
resolves to a page linking the song across services.

```json
{ "result": { "song_link": "https://lis.tn/NbkVb" } }
```

Append `?thumb` to a `song_link` to get the cover art directly
(`https://lis.tn/NbkVb?thumb`), without requesting any provider block.

So before adding providers to `return`, ask whether `song_link` already
covers the need. Request provider blocks when you need a **specific
service's** direct URL, IDs, preview, or artwork in your own UI; reach for
`song_link` when a cross-provider link and cover art are enough. See the
[lis.tn song link concept](/resources/concepts/lisn-song-link) for the full
behavior.

## SDK helpers: `streaming_url(provider)`

The SDKs expose a helper that resolves a per-provider URL from a match:
`streaming_url(provider)` in Python, `streamingUrl(provider)` in the
camelCase SDKs. It returns the direct provider URL when you requested that
block, and otherwise falls back to the lis.tn redirect for that provider —
so it works whether or not you set `return`.

```python
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["spotify"],
)
result.streaming_url("spotify")      # direct open.spotify.com/track/… (block was requested)
result.streaming_url("apple_music")  # lis.tn redirect (block was not requested)
```

```ts
const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["spotify"],
});
result.streamingUrl("spotify");      // direct Spotify URL
result.streamingUrl("apple_music");  // lis.tn redirect
```

Valid provider identifiers: `spotify`, `apple_music`, `deezer`,
`youtube`. (`youtube` resolves only through lis.tn — there is no `youtube`
metadata block. MusicBrainz is a metadata database, not a streaming
service, so it has no `streaming_url` either.)

## Notes

- Requesting a provider does not guarantee its block appears: AudD returns
  it only when that provider has a match for the recognized recording.
  Always null-check before reading.
- The `market` parameter only affects Apple Music and Spotify lookups.
- ISRC is a reliable join key when you store metadata from more than one
  provider — the same ISRC appears across the Apple Music, Spotify, and
  MusicBrainz blocks for the same recording.

---

**Related**

- [Apple Music metadata block](/resources/reference/apple-music)
- [Spotify metadata block](/resources/reference/spotify)
- [Deezer metadata block](/resources/reference/deezer)
- [Napster metadata block (no longer available)](/resources/reference/napster)
- [MusicBrainz metadata block](/resources/reference/musicbrainz)
- [The lis.tn song link](/resources/concepts/lisn-song-link)
- [Result fields reference](/resources/reference/result-fields)
- [Glossary](/resources/reference/glossary)
- [SDK docs](https://docs.audd.io/sdks)