Apple Music charts
Return the current Apple Music songs, albums, music-videos or playlists chart as canonical post rows. Select the top 1–100 positions (default 50), then filter by release date while retaining original ranks and undated rows. Country codes are case-insensitive and uk aliases gb. Unsupported storefronts return an uncharged 400. Dates describe releases, not historical chart snapshots. Unknown engagement, verification badges and computed estimates remain null. Exact requests are cached for one hour. Costs one credit for nonempty fresh results; empty results, errors and cache/idempotency replays are free.
country defaults to us, accepts any case and maps uk to gb. The adapter validates countries against Apple’s 172-storefront music directory, captured October 12, 2026; countries outside that directory return a free 400 UNSUPPORTED_COUNTRY. Upstream outages remain errors, never empty charts.
limit selects the top 1–100 chart positions, default 50. Each item contains a canonical post and computed object. Titles, artwork, artist names, public Apple URLs and release dates come from the feed. post.ext.trend.rank preserves the original position, country_code uses uppercase ISO codes, and updated_at is Apple’s chart update time. post.ext.apple_music retains kind, release date, artist ID/URL, genres and content advisory. The feed supplies metadata, not playable media or listening counts.
since and until filter release dates after the top positions are selected, not historical chart positions. Calendar dates use UTC; until includes the entire day. Undated entries remain. Playlists have no artist or release date, so these fields stay null. Missing compilation-artist IDs and genre IDs also stay null. Date aliases must agree with explicit bounds. publish_time uses rolling windows of 1, 7, 30, 90 or 180 days; max_age_days accepts 0–36500.
Fresh nonempty results cost 1 credit. Empty filtered results, errors, cache hits and successful idempotent replays cost zero. Use X-Max-Credits: 1 to cap spending. Exact requests are cached for one hour; Cache-Control: no-cache requests a fresh chart.
total and returned_count count returned rows. source_count is the size of the current feed (at most 100), and filtered_count counts selected positions excluded by dates. There is no continuation cursor. Unknown engagement, badges, language and reach estimates remain null; they are not fabricated from rank.Authorizations
Headers
Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero.
x >= 0Query Parameters
Apple Music country code, case-insensitive; uk maps to gb. Unknown storefronts return free 400.
songs, albums, music-videos, playlists Top chart positions to select before release-date filtering; default 50.
1 <= x <= 100Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Release-date alias. Explicit aliases must agree. publish_time accepts rolling windows yesterday (1 day), this-week (7), this-month (30), last-3-months (90), last-6-months (180); max_age_days accepts 0–36500. Undated rows are retained.
Response
Return the current Apple Music songs, albums, music-videos or playlists chart as canonical post rows. Select the top 1–100 positions (default 50), then filter by release date while retaining original ranks and undated rows. Country codes are case-insensitive and uk aliases gb. Unsupported storefronts return an uncharged 400. Dates describe releases, not historical chart snapshots. Unknown engagement, verification badges and computed estimates remain null. Exact requests are cached for one hour. Costs one credit for nonempty fresh results; empty results, errors and cache/idempotency replays are free.
x >= 0The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null.