SignalApple Music · track
Read a public Apple Music song. GET /api/v1/apple-music/track 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. Song URLs with an `?i=` track identifier are supported. Audio previews and artwork are omitted. 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/track?" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/apple-music/track?", {
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/track?",
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.
A track lookup returns one public catalog record. Song previews and audio bytes are not returned.
Track data.data includes catalog ID, title, artist and album identifiers/names, catalog URL, duration, track number, release date, genre, and nullable explicitness when supplied by Apple. Song previews, artwork, and audio bytes are omitted.
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.