SignalApple Music · search
Search the public Apple music catalog. GET /api/v1/apple-music/search 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 Search API. Supported types are all, artist, album, song, and music_video; playlist, station, and radio_episode reference types are not available from this source. Artwork and audio preview URLs are omitted. Apple Search API terms govern commercial display and reuse.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Catalog search query. |
type | string | No | Supported public catalog result type. Allowed: all, artist, album, song, music_video. Default: all. |
storefront | string | No | Two-letter storefront country code; defaults to the US catalog. |
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/search?query=Taylor+Swift" \
-H "x-api-key: $SIGNALSHELF_API_KEY"const response = await fetch(process.env.SIGNALSHELF_BASE_URL + "/api/v1/apple-music/search?query=Taylor+Swift", {
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/search?query=Taylor+Swift",
headers={'x-api-key': os.environ['SIGNALSHELF_API_KEY']},
timeout=30,
)
response.raise_for_status()
print(response.json())Response and pagination
Search returns data.results, result_count, type and storefront. Results are normalized from Apple’s public iTunes catalog; they do not include personalized library data or playable audio.
Search returns at most 50 results. The source does not provide a continuation cursor here; playlist, station and radio-episode types from the reference contract are unsupported.
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.