SignalApple Music · album
Read a public Apple Music album and its tracks. GET /api/v1/apple-music/album accepts your x-api-key header. Production live requests are disabled pending review of Apple's Search API terms for this paid data-resale use.
Request parameters
Uses Apple’s public iTunes Lookup catalog. Returns album metadata and the catalog tracks exposed by the lookup response. Apple Search API terms govern commercial display and reuse.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | No | Numeric Apple Music catalog identifier. |
url | string | No | Apple Music artist, album, or song URL on music.apple.com. |
storefront | string | No | Two-letter storefront country code. A country in the supplied URL takes precedence. |
freshness | string | No | 24h (default), 1h, 7d, or live. Accepted cache hits are free; live forces refresh except simultaneous requests may share newly fetched data. |
Code examples
Set SIGNALSHELF_BASE_URL and SIGNALSHELF_API_KEY on your server.
curl "$SIGNALSHELF_BASE_URL/api/v1/apple-music/album?" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/apple-music/album?", {
headers: { 'x-api-key': process.env.SIGNALSHELF_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data, body.meta);import os, requests
response = requests.get(
os.environ['SIGNALSHELF_BASE_URL'] + "/api/v1/apple-music/album?",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
Artist, album and track details are returned under data.data with the public catalog fields Apple exposed. Artist includes up to 12 albums, 24 songs and 12 music videos when available; album includes tracks. Artwork and preview URLs are omitted. Catalog links are retained for attribution and click-through. This uses the iTunes Search/Lookup API, not Apple Music API or exact reference response parity. Commercial display and reuse are subject to Apple Search API terms.
Album lookup returns up to 200 tracks if the selected storefront provides them. There is no continuation cursor.
Album data.data includes catalog ID, title, artist, URL, track count, release date, copyright, release_info, and up to 200 normalized tracks. Track rows include ID, title, duration, track number, album ID, artist name, and URL when supplied by Apple.
The compatibility GET alias also places the normalized resource fields at the response root and retains the complete native result under data. Search aliases expose query, type, storefront, result_count and results at the root as well as under data. These field names and nesting are SignalShelf’s documented mapping, not a claim of exact source-response parity.
meta includes event_id, mode, cache, credits_charged, fetched_at, age_seconds, and duration_ms. A fresh successful result costs one credit; accepted cached results and failures cost zero.
Availability and failures
Implementation is not a continuous availability guarantee. Source rate limits, retention, deleted content, restrictions, and regional availability apply. This is an independent SignalShelf contract, not a drop-in competitor response format.
400: invalid parameters. 401: missing/revoked key. 402: insufficient credits. 404: missing public resource. 429: SignalShelf throttle. 502/503: upstream failure or rate limit, with credit restored.