API REFERENCE

Get Album

On this page

GET/api/spotify/album

Get Spotify catalog information for a single album.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/spotify/album?id=YOUR_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Query parameters

idstringrequired

The Spotify ID of the album

marketstring

An ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned

Responses

200Album retrieved successfully

application/json

album_typestring · enum

The type of the album

Values: "album", "single", "compilation"

total_tracksinteger

The number of tracks in the album

available_marketsarray<string>

Markets in which the album is available

Item properties

string

external_urlsobject

Properties

spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the album

imagesarray<SpotifyImage>

The cover art for the album in various sizes

Item properties

urlstring

The source URL of the image

heightintegernullable

The image height in pixels

widthintegernullable

The image width in pixels

namestring

The name of the album

release_datestring

The date the album was first released

release_date_precisionstring · enum

The precision with which release_date value is known

Values: "year", "month", "day"

restrictionsobject

Included when a content restriction is applied

Properties

reasonstring

typestring · enum

The object type, always 'album'

Values: "album"

uristring

The Spotify URI for the album

artistsarray<SpotifySimplifiedArtist>

The artists of the album

Item properties

external_urlsobject

Properties

spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the artist

namestring

The name of the artist

typestring · enum

The object type, always 'artist'

Values: "artist"

uristring

The Spotify URI for the artist

tracksobject

The tracks of the album

Properties

hrefstring

A link to the Web API endpoint

limitinteger

The maximum number of items in the response

nextstringnullable

URL to the next page of items

offsetinteger

The offset of the items returned

previousstringnullable

URL to the previous page

totalinteger

Total number of items available

itemsarray<SpotifySimplifiedTrack>

Array of simplified track objects

Item properties

artistsarray<SpotifySimplifiedArtist>

The artists who performed the track

Item properties

external_urlsobject

Properties

spotifystring

The Spotify URL for the object

hrefstring

A link to the Web API endpoint providing full details

idstring

The Spotify ID for the artist

namestring

The name of the artist

typestring · enum

The object type, always 'artist'

Values: "artist"

uristring

The Spotify URI for the artist

available_marketsarray<string>

Markets in which the track is available

Item properties

string

disc_numberinteger

Disc number the track is on

duration_msinteger

Track length in milliseconds

explicitboolean

Whether the track has explicit lyrics

external_urlsobject

Properties

spotifystring

The Spotify URL for the object

hrefstring

Link to the Web API endpoint

idstring

Spotify ID for the track

is_playableboolean

If true, the track is playable

linked_fromobject

Track relinking info

restrictionsobject

Properties

reasonstring

namestring

Track name

preview_urlstringnullable

URL to a 30 second preview

track_numberinteger

Track number on the album

typestring · enum

Values: "track"

uristring

Spotify URI for the track

is_localboolean

Whether from a local file

copyrightsarray<SpotifyCopyright>

Item properties

textstring

The copyright text

typestring

The type of copyright

external_idsobject

Known external IDs for the album

Properties

isrcstring

eanstring

upcstring

genresarray<string>

Deprecated. Always empty.

Item properties

string

labelstring

The label associated with the album

popularityinteger

Popularity of the album (0-100)

400Bad request - missing required parameters

application/json

errorobject

Error details

Properties

statusinteger

HTTP status code

messagestring

Error message

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download social.json

View operation source

json

{
  "description": "Get Spotify catalog information for a single album.",
  "parameters": [
    {
      "name": "id",
      "in": "query",
      "description": "The Spotify ID of the album",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "market",
      "in": "query",
      "description": "An ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned",
      "required": false,
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Album retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyAlbum"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing required parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SpotifyErrorResponse"
          }
        }
      }
    }
  }
}