---
title: "Apple Music metadata block"
description: "How to request and read the Apple Music metadata block on an AudD match: the track URL, AAC preview, artwork template, catalog ID, and ISRC."
slug: "/resources/reference/apple-music"
section: "reference"
keywords: [audd, apple music metadata, apple music url, artwork, preview, isrc]
---

# Apple Music metadata block

The `apple_music` block attaches Apple Music's own metadata for the
recognized recording to the match. It mirrors an Apple Music
[Songs](https://developer.apple.com/documentation/applemusicapi/songs)
attributes object, so you get a direct Apple Music URL, a 30-second AAC
preview, artwork, and the catalog ID without a second call. It is present
only when you request it — and only when Apple Music has a match for the
recording.

## How to request it

In the SDKs, list the provider in the `return_metadata` option (Python) /
`returnMetadata` (Node):

```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"],
)
```

```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"],
});
```

In raw curl, the form field is named `return` (the SDK option above is the
SDK name for the same thing):

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

The `market` parameter sets the country code for the Apple Music lookup
(defaults to `us`); it changes which catalog entry you get back.

## How to access it

The block is the typed `apple_music` property on the result, and its
sub-fields are typed attributes on that model — attribute access, not dict
subscripts. Fields beyond the typed ones (composer, work, audio traits, the
`artwork` and `previews` objects) round-trip through Pydantic's
`model_extra` in Python / `extras` in Node.

```python
result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music"],
)
am = result.apple_music                 # None if not requested / no Apple Music match
if am:
    page = am.url                       # Apple Music page for the track
    title = am.name
    code = am.isrc
    # untyped fields (artwork, previews, playParams, …) via model_extra
    artwork = (am.model_extra or {}).get("artwork")
```

```ts
const am = result.appleMusic;           // undefined if not requested / no match
if (am) {
  const page = am.url;                  // typed-equivalent fields live on the block
  const artwork = am.artwork;           // untyped fields readable via the block / extras
}
```

A couple of fields need handling:

- `artwork.url` is a **template**, not a final image URL: it contains
  literal `{w}` and `{h}` placeholders. Substitute the pixel size you want
  before using it — e.g. replace `{w}x{h}` with `300x300` for a 300×300
  cover. `artwork.width`/`artwork.height` give the maximum available size.
- `previews[0].url` is a 30-second AAC preview you can play directly. Use it
  subject to Apple Music's terms.

## Fields

The typed fields on the Apple Music block:

| Field | Type | Description |
|---|---|---|
| `name` | string \| null | Track title. |
| `artistName` | string \| null | Artist name. |
| `albumName` | string \| null | Album the track appears on. |
| `url` | string \| null | Apple Music page for the track. |
| `isrc` | string \| null | The recording's ISRC. |
| `durationInMillis` | int \| null | Track length in milliseconds. |
| `trackNumber` | int \| null | Position on the album. |
| `discNumber` | int \| null | Disc number. |
| `composerName` | string \| null | Composer. |
| `releaseDate` | string \| null | Release date (`YYYY-MM-DD`). |

Apple's response carries more — `artwork`, `previews`, `playParams`,
`genreNames`, `hasLyrics`, `isAppleDigitalMaster`, and others. These aren't
typed properties; read them through the block's `model_extra` (Python) /
`extras` (Node). For the full attribute list see Apple's
[Song attributes reference](https://developer.apple.com/documentation/applemusicapi/songs/attributes).

The block and every field can be absent or null — request did not include
`apple_music`, no Apple Music match for the recording, or the provider
omitted a field. Always null-check before reading.

## Without requesting the block: `song_link`

You don't need the `apple_music` block just to send a user to Apple Music.
Every match carries a `song_link` (a lis.tn URL such as
`https://lis.tn/NbkVb`), and the `streaming_url("apple_music")` SDK helper
(`streamingUrl("apple_music")` in Node) returns an "open in Apple Music"
redirect built from it — no provider block, no added latency:

```python
result.streaming_url("apple_music")   # lis.tn ?apple_music redirect
```

Request the `apple_music` block when you need the structured metadata —
direct URL, catalog ID, preview, artwork — in your own UI. See the
[lis.tn song link](/resources/concepts/lisn-song-link) concept for the
redirect convention.

---

**Related**

- [Spotify metadata block](/resources/reference/spotify)
- [Deezer metadata block](/resources/reference/deezer)
- [MusicBrainz metadata block](/resources/reference/musicbrainz)
- [The lis.tn song link](/resources/concepts/lisn-song-link)
- [Provider metadata overview](/resources/reference/provider-metadata)