Get User's Saved Audiobooks

me.audiobooks.list() -> SyncCursorURLPage[AudiobookListResponse]

GET/me/audiobooks

Get a list of the audiobooks saved in the current Spotify user's 'Your Music' library.

ParametersExpand Collapse

limit: Optional[int]

The maximum number of items to return. Default: 20. Minimum: 1. Maximum: 50.

minimum1

maximum50

offset: Optional[int]

The index of the first item to return. Default: 0 (the first item). Use with limit to get the next set of items.

ReturnsExpand Collapse

class AudiobookListResponse: …

added_at: Optional[datetime]

The date and time the audiobook was saved Timestamps are returned in ISO 8601 format as Coordinated Universal Time (UTC) with a zero offset: YYYY-MM-DDTHH:MM:SSZ. If the time is imprecise (for example, the date/time of an album release), an additional field indicates the precision; see for example, release_date in an album object.

formatdate-time

audiobook: Optional[Audiobook]

Information about the audiobook.

chapters: AudiobookChapters

The chapters of the audiobook.

href: str

A link to the Web API endpoint returning the full result of the request

limit: int

The maximum number of items in the response (as set in the query or by default).

next: Optional[str]

URL to the next page of items. ( null if none)

offset: int

The offset of the items returned (as set in the query or by default)

previous: Optional[str]

URL to the previous page of items. ( null if none)

total: int

The total number of items available to return.

items: Optional[List[SimplifiedChapterObject]]

id: str

The Spotify ID for the chapter.

Deprecatedaudio_preview_url: Optional[str]

A URL to a 30 second preview (MP3 format) of the chapter. null if not available.

chapter_number: int

The number of the chapter

description: str

A description of the chapter. HTML tags are stripped away from this field, use html_description field in case HTML tags are needed.

duration_ms: int

The chapter length in milliseconds.

explicit: bool

Whether or not the chapter has explicit content (true = yes it does; false = no it does not OR unknown).

external_urls: ExternalURLObject

External URLs for this chapter.

published: Optional[bool]

The playlist's public/private status (if it should be added to the user's profile or not): true the playlist will be public, false the playlist will be private, null the playlist status is not relevant. For more about public/private status, see Working with Playlists

spotify: Optional[str]

The Spotify URL for the object.

href: str

A link to the Web API endpoint providing full details of the chapter.

html_description: str

A description of the chapter. This field may contain HTML tags.

images: List[ImageObject]

The cover art for the chapter in various sizes, widest first.

height: Optional[int]

The image height in pixels.

url: str

The source URL of the image.

width: Optional[int]

The image width in pixels.

published: Optional[bool]

is_playable: bool

True if the chapter is playable in the given market. Otherwise false.

languages: List[str]

A list of the languages used in the chapter, identified by their ISO 639-1 code.

name: str

The name of the chapter.

release_date: str

The date the chapter was first released, for example "1981-12-15". Depending on the precision, it might be shown as "1981" or "1981-12".

release_date_precision: Literal["year", "month", "day"]

The precision with which release_date value is known.

Accepts one of the following:

"year"

"month"

"day"

type: Literal["episode"]

The object type.

uri: str

The Spotify URI for the chapter.

available_markets: Optional[List[str]]

A list of the countries in which the chapter can be played, identified by their ISO 3166-1 alpha-2 code.

published: Optional[bool]

restrictions: Optional[ChapterRestrictionObject]

Included in the response when a content restriction is applied.

published: Optional[bool]

reason: Optional[str]

The reason for the restriction. Supported values:

market - The content item is not available in the given market.
product - The content item is not available for the user's subscription type.
explicit - The content item is explicit and the user's account is set to not play explicit content.
payment_required - Payment is required to play the content item.

Additional reasons may be added in the future. Note: If you use this field, make sure that your application safely handles unknown values.

resume_point: Optional[ResumePointObject]

The user's most recent position in the chapter. Set if the supplied access token is a user token and has the scope 'user-read-playback-position'.

fully_played: Optional[bool]

Whether or not the episode has been fully played by the user.

published: Optional[bool]

resume_position_ms: Optional[int]

The user's most recent position in the episode in milliseconds.

published: Optional[bool]

Get User's Saved Audiobooks

import os
from spotted import Spotted

client = Spotted(
    access_token=os.environ.get("SPOTIFY_ACCESS_TOKEN"),  # This is the default and can be omitted
)
page = client.me.audiobooks.list()
page = page.items[0]
print(page.added_at)

{
  "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
  "limit": 20,
  "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "total": 4,
  "items": [
    {
      "added_at": "2019-12-27T18:11:19.117Z",
      "audiobook": {
        "id": "id",
        "authors": [
          {
            "name": "name",
            "published": true
          }
        ],
        "available_markets": [
          "string"
        ],
        "copyrights": [
          {
            "published": true,
            "text": "text",
            "type": "type"
          }
        ],
        "description": "description",
        "explicit": true,
        "external_urls": {
          "published": true,
          "spotify": "spotify"
        },
        "href": "href",
        "html_description": "html_description",
        "images": [
          {
            "height": 300,
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "width": 300,
            "published": true
          }
        ],
        "languages": [
          "string"
        ],
        "media_type": "media_type",
        "name": "name",
        "narrators": [
          {
            "name": "name",
            "published": true
          }
        ],
        "publisher": "publisher",
        "total_chapters": 0,
        "type": "audiobook",
        "uri": "uri",
        "edition": "Unabridged",
        "published": true,
        "chapters": {
          "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
          "limit": 20,
          "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
          "offset": 0,
          "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
          "total": 4,
          "items": [
            {
              "id": "5Xt5DXGzch68nYYamXrNxZ",
              "audio_preview_url": "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17",
              "chapter_number": 1,
              "description": "We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.\n",
              "duration_ms": 1686230,
              "explicit": true,
              "external_urls": {
                "published": true,
                "spotify": "spotify"
              },
              "href": "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ",
              "html_description": "<p>We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.</p>\n",
              "images": [
                {
                  "height": 300,
                  "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
                  "width": 300,
                  "published": true
                }
              ],
              "is_playable": true,
              "languages": [
                "fr",
                "en"
              ],
              "name": "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators\n",
              "release_date": "1981-12-15",
              "release_date_precision": "day",
              "type": "episode",
              "uri": "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr",
              "available_markets": [
                "string"
              ],
              "published": true,
              "restrictions": {
                "published": true,
                "reason": "reason"
              },
              "resume_point": {
                "fully_played": true,
                "published": true,
                "resume_position_ms": 0
              }
            }
          ],
          "published": true
        }
      },
      "published": true
    }
  ],
  "published": true
}

Returns Examples

{
  "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
  "limit": 20,
  "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "offset": 0,
  "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
  "total": 4,
  "items": [
    {
      "added_at": "2019-12-27T18:11:19.117Z",
      "audiobook": {
        "id": "id",
        "authors": [
          {
            "name": "name",
            "published": true
          }
        ],
        "available_markets": [
          "string"
        ],
        "copyrights": [
          {
            "published": true,
            "text": "text",
            "type": "type"
          }
        ],
        "description": "description",
        "explicit": true,
        "external_urls": {
          "published": true,
          "spotify": "spotify"
        },
        "href": "href",
        "html_description": "html_description",
        "images": [
          {
            "height": 300,
            "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
            "width": 300,
            "published": true
          }
        ],
        "languages": [
          "string"
        ],
        "media_type": "media_type",
        "name": "name",
        "narrators": [
          {
            "name": "name",
            "published": true
          }
        ],
        "publisher": "publisher",
        "total_chapters": 0,
        "type": "audiobook",
        "uri": "uri",
        "edition": "Unabridged",
        "published": true,
        "chapters": {
          "href": "https://api.spotify.com/v1/me/shows?offset=0&limit=20\n",
          "limit": 20,
          "next": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
          "offset": 0,
          "previous": "https://api.spotify.com/v1/me/shows?offset=1&limit=1",
          "total": 4,
          "items": [
            {
              "id": "5Xt5DXGzch68nYYamXrNxZ",
              "audio_preview_url": "https://p.scdn.co/mp3-preview/2f37da1d4221f40b9d1a98cd191f4d6f1646ad17",
              "chapter_number": 1,
              "description": "We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.\n",
              "duration_ms": 1686230,
              "explicit": true,
              "external_urls": {
                "published": true,
                "spotify": "spotify"
              },
              "href": "https://api.spotify.com/v1/episodes/5Xt5DXGzch68nYYamXrNxZ",
              "html_description": "<p>We kept on ascending, with occasional periods of quick descent, but in the main always ascending. Suddenly, I became conscious of the fact that the driver was in the act of pulling up the horses in the courtyard of a vast ruined castle, from whose tall black windows came no ray of light, and whose broken battlements showed a jagged line against the moonlit sky.</p>\n",
              "images": [
                {
                  "height": 300,
                  "url": "https://i.scdn.co/image/ab67616d00001e02ff9ca10b55ce82ae553c8228\n",
                  "width": 300,
                  "published": true
                }
              ],
              "is_playable": true,
              "languages": [
                "fr",
                "en"
              ],
              "name": "Starting Your Own Podcast: Tips, Tricks, and Advice From Anchor Creators\n",
              "release_date": "1981-12-15",
              "release_date_precision": "day",
              "type": "episode",
              "uri": "spotify:episode:0zLhl3WsOCQHbe1BPTiHgr",
              "available_markets": [
                "string"
              ],
              "published": true,
              "restrictions": {
                "published": true,
                "reason": "reason"
              },
              "resume_point": {
                "fully_played": true,
                "published": true,
                "resume_position_ms": 0
              }
            }
          ],
          "published": true
        }
      },
      "published": true
    }
  ],
  "published": true
}