Album API: one schema on 2 platforms

Endpoints

5 endpoints return albums on Apple Music and Spotify.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (applemusic, spotify, soundcloud, …).

idstring

Platform-native album ID (string), the one in its page's URL.

urlstring uri

Canonical album page URL.

typestringnullable

What kind of release it is, as the platform says: album, single, ep or compilation; null when the platform does not say. New values may be added; treat unknown values as album.

One ofalbumsingleepcompilation

titlestring

The release's title as the platform shows it (with an edition or a suffix like "- Single" where it writes one).

descriptionstringnullable

About the release, as plain text (the service's editorial notes, or what its uploader wrote); null when it has none or the platform shows none.

artist_namestringnullable

Who the platform credits for the release, as one display string (it can name more people than have an account linked: artists holds the linked ones); null when the source does not name them.

artistsobject[]

The platform accounts of the artists credited on the release, main artist first, in the platform's order; [] when none is linked, as on a Various Artists compilation (listed in unknown_fields when the source cannot see them).

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

cover_urlstring urinullable

Cover art URL at the largest size the platform serves; null when it has none.

released_atstring date-timenullable

When it was released, RFC 3339 UTC. A release date with no time (nearly all) is midnight UTC of that date, listed in approximate_fields, and so is a year or month alone (its first day). Null when the platform states none.

labelstringnullable

The record label as the platform names it; null when none is shown.

upcstringnullable

The release's barcode: its UPC or EAN, digits only; null when the platform does not show it.

copyrightsobject[]

The release's copyright lines as the platform shows them; [] when none.

Show 2 child fields

typestringnullable

c: the copyright in the work (©); p: in the sound recording (℗); null when the line does not say or states both. New values may be added.

One ofcp

textstring

The line as the platform shows it.

genresstring[]

Genres the platform files it under, as shown (not normalized), the main one first; [] when none (listed in unknown_fields when the source cannot see them).

is_explicitbooleannullable

Marked as holding explicit content (by the platform, or on any of its tracks); null when the platform does not say.

duration_msintegernullable

Total length of the release in milliseconds; null when neither the platform nor a complete tracks list gives it.

tracksobject[]

The release's tracks in album order (by disc, then track number). A list of albums, whose source shows none, answers [] and lists tracks in unknown_fields; a list the source could only read part of is listed in approximate_fields.

Show 12 child fields

idstring

Platform-native track ID (string): the one the platform's track endpoint takes and answers.

urlstring urinullable

The track's page; null when the source does not show it.

titlestringnullable

The track's title as the platform shows it; null when the source names the track only by its ID.

artist_namestringnullable

Who the platform credits for this track, as one display string (a feature included); null when the source does not name them.

artistsobject[]

The platform accounts of the artists credited on this track, in the platform's order; [] when none is linked (listed in unknown_fields as tracks[].artists when the source cannot see them).

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

track_numberintegernullable

Its position on its disc, from 1; null when the source does not state it (tracks stay in album order).

disc_numberintegernullable

The disc it is on, from 1; null when the platform does not say (a release of one disc, on platforms without discs).

duration_msintegernullable

Length of the track in milliseconds; null when the source does not state it.

is_explicitbooleannullable

Marked as explicit by the platform; null when it does not say.

isrcstringnullable

International Standard Recording Code, 12 characters without hyphens; null when the platform does not show it.

play_urlstring urinullable

Audio file URL: a short preview, where the platform serves only one. Signed links expire within hours; null when not exposed.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 1 child field

view_countintegernullable

Plays; null when the platform does not show them.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 1 child field

track_countintegernullable

Tracks on the release as the platform counts them, null when it does not state a count; tracks answers fewer only when listed in approximate_fields or unknown_fields.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 3 child fields

soundcloudobjectnullable

A SoundCloud album set's own fields.

Show 10 child fields

permalinkstringnullable

The set's name in its link (soundcloud.com/<artist>/sets/<permalink>).

tagsstring[]

The uploader's tags, without the quotes SoundCloud keeps around a tag of several words; [] when none.

licensestringnullable

The license the set is published under (all-rights-reserved, cc-by, …).

published_atstring date-timenullable

When the set went public on SoundCloud, RFC 3339 UTC; null when SoundCloud does not say.

uploaded_atstring date-timenullable

When the set was created on SoundCloud, RFC 3339 UTC.

last_modified_atstring date-timenullable

When the uploader last changed the set, RFC 3339 UTC.

embeddable_bystringnullable

Who may embed the player (all, me, none).

purchase_urlstring urinullable

The buy link the uploader set; null when none.

purchase_titlestringnullable

The label of the buy link; null when SoundCloud's default is used.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 2 child fields

like_countintegernullable

Likes of the set (its tracks' likes are their own).

repost_countintegernullable

Reposts of the set.

spotifyobjectnullable

A Spotify release's own fields.

Show 5 child fields

release_date_precisionstringnullable

How much of released_at Spotify states: day, month or year. New values may be added.

One ofdaymonthyear

is_pre_releasebooleannullable

Announced and not out yet.

pre_release_ends_atstring date-timenullable

When a pre-release comes out, RFC 3339 UTC; null on a release that is out.

is_playablebooleannullable

Spotify plays it in the country SocialTap asked from, which is not necessarily yours.

popularityintegernullable

Spotify's own score for this release, 0 to 100 and recent plays weighing most.

applemusicobjectnullable

An Apple Music album's own fields.

Show 10 child fields

storefrontstringnullable

The Apple Music store this answer is from, as a lowercase country code (us, jp): titles, availability, track lists and links differ by store.

rankintegernullable

Position on the requested chart (1 = top); null off a chart.

editorial_summarystringnullable

Apple's one-line note on the album; null when none.

content_ratingstringnullable

explicit, or clean for an edited version of something explicit; null when Apple marks neither.

audio_traitsstring[]

The audio formats it comes in (atmos, lossless, lossy-stereo, spatial, …); [] when none or the source does not show them (listed in unknown_fields). New values may be added.

is_completebooleannullable

Every track of the release is available in this store.

is_prereleasebooleannullable

Announced, and not released yet.

is_mastered_for_itunesbooleannullable

Carries Apple's Mastered for iTunes badge, which Apple now calls Apple Digital Master.

more_by_artistobject[]

Apple's other releases by the same artist, as many as its page shows at first; [] when none or the source does not show them (listed in unknown_fields).

Show 10 child fields

idstring

Apple Music's ID of the item (string).

kindstring

What it is. New values may be added.

One ofsongmusic_videoalbumplaylistartiststation

urlstring urinullable

Its page; null when Apple does not state it.

titlestringnullable

Its title, or an artist's name.

artist_namestringnullable

Who Apple credits for it, or a playlist's curator; null on an artist.

cover_urlstring urinullable

Its artwork at the largest size Apple states; null when none.

released_atstring date-timenullable

Its release date, midnight UTC of that date; null when Apple does not state it.

track_countintegernullable

An album's tracks, null on other kinds.

duration_msintegernullable

A song's or music video's length in milliseconds, null on other kinds.

is_explicitbooleannullable

Apple marks it explicit; null on kinds it does not mark.

other_versionsobject[]

Other versions of the release (the clean or explicit one, a deluxe edition); [] when none or the source does not show them (listed in unknown_fields).

Show 10 child fields

idstring

Apple Music's ID of the item (string).

kindstring

What it is. New values may be added.

One ofsongmusic_videoalbumplaylistartiststation

urlstring urinullable

Its page; null when Apple does not state it.

titlestringnullable

Its title, or an artist's name.

artist_namestringnullable

Who Apple credits for it, or a playlist's curator; null on an artist.

cover_urlstring urinullable

Its artwork at the largest size Apple states; null when none.

released_atstring date-timenullable

Its release date, midnight UTC of that date; null when Apple does not state it.

track_countintegernullable

An album's tracks, null on other kinds.

duration_msintegernullable

A song's or music video's length in milliseconds, null on other kinds.

is_explicitbooleannullable

Apple marks it explicit; null on kinds it does not mark.

approximate_fieldsstring[]

JSON paths of values that are date-only, rounded by the platform or parsed from display text (released_at from a date, duration_ms from "1 hour 1 minute"). A list path means the list may be incomplete. [] when all exact.

unknown_fieldsstring[]

JSON paths of lists whose [] means unknown rather than none (a source that cannot see them), tracks[].artists for that list on every track; null already means unknown for every other field. [] when every list is known.

Item errors

Besides the request-level errors every endpoint can return, album endpoints return:

Code	HTTP	Retry	Meaning	What to do
`not_found`	404	No	The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why).	Check the link or ID. Do not retry.
`private_or_unavailable`	403	No	The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code.	Only public items can be fetched. Do not retry.