AudiobooksAPI

class minim.api.spotify.AudiobooksAPI(client: APIClient, /)[source]

Bases: SpotifyResourceAPI

Audiobooks API endpoints for the Spotify Web API.

Important

Audiobooks are only available in the US, UK, Canada, Ireland, New Zealand, and Australia markets.

Important

This class is managed by SpotifyWebAPIClient and should not be instantiated directly.

Parameters:
clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

are_audiobooks_saved

Audiobooks > Check User's Saved Audiobooks: Check whether one or more audiobooks are saved in the current user's library.

get_audiobook_chapters

Audiobooks > Get Audiobook Chapters: Get Spotify catalog information for chapters in an audiobook.

get_audiobooks

Audiobooks > Get an Audiobook: Get Spotify catalog information for an audiobook․ Audiobook > Get Several Audiobooks: Get Spotify catalog information for multiple audiobooks.

get_my_saved_audiobooks

Audiobooks > Get User's Saved Audiobooks: Get Spotify catalog information for the audiobooks saved in the current user's library.

remove_saved_audiobooks

Audiobooks > Remove User's Saved Audiobooks: Remove one or more audiobooks from the current user's library.

save_audiobooks

Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to the current user's library.
are_audiobooks_saved(audiobook_ids: str | Collection[str], /) → list[bool][source]

Audiobooks > Check User’s Saved Audiobooks: Check whether one or more audiobooks are saved in the current user’s library.

Authorization scope

user-library-read scope

Access your saved content. Learn more.

Parameters:
audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "18yVqkdbdRvS24c0Ilj2ci"

  • "18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"

  • ["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

Returns:
savedlist[bool]

Whether the current user has the specified audiobooks saved in their library.

get_audiobook_chapters(audiobook_id: str, /, *, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Audiobooks > Get Audiobook Chapters: Get Spotify catalog information for chapters in an audiobook.

Third-party application mode

user-read-playback-position scope

Read your position in content you have played. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
audiobook_idstr; positional-only

Spotify ID of the audiobook.

Examples: "18yVqkdbdRvS24c0Ilj2ci".

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of audiobook chapters to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first audiobook chapter to return. Use with limit to get the next batch of audiobook chapters.

Minimum value: 0.

API default: 0.

Returns:
chaptersdict[str, Any]

Page of Spotify metadata for the audiobook’s chapters.

Sample response

{
  "href": <str>,
  "items": [
    {
      "audio_preview_url": <str>,
      "available_markets": <list[str]>,
      "chapter_number": <int>,
      "description": <str>,
      "duration_ms": <int>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "html_description": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "is_playable": <bool>,
      "languages": <list[str]>,
      "name": <str>,
      "release_date": <str>,
      "release_date_precision": <str>,
      "restrictions": {
        "reason": <str>
      },
      "resume_point": {
        "fully_played": <bool>,
        "resume_position_ms": <int>
      },
      "type": "chapter",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}
get_audiobooks(audiobook_ids: str | Collection[str], /, *, country_code: str | None = None) → dict[str, Any][source]

Audiobooks > Get an Audiobook: Get Spotify catalog information for an audiobook․ Audiobook > Get Several Audiobooks: Get Spotify catalog information for multiple audiobooks.

Third-party application mode

user-read-playback-position scope

Read your position in content you have played. Learn more.

Extended quota mode before November 27, 2024

Access 30-second preview URLs. Learn more.

Parameters:
audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "18yVqkdbdRvS24c0Ilj2ci"

  • "18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"

  • ["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

Returns:
audiobooksdict[str, Any]

Spotify metadata for the audiobooks.

Sample responses

{
  "authors": [
    {
      "name": <str>
    }
  ],
  "available_markets": <list[str]>,
  "chapters": {
    "href": <str>,
    "items": [
      {
        "audio_preview_url": <str>,
        "available_markets": <list[str]>,
        "chapter_number": <int>,
        "description": <str>,
        "duration_ms": <int>,
        "explicit": <bool>,
        "external_urls": {
          "spotify": <str>
        },
        "href": <str>,
        "html_description": <str>,
        "id": <str>,
        "images": [
          {
            "height": <int>,
            "url": <str>,
            "width": <int>
          }
        ],
        "is_playable": <bool>,
        "languages": <list[str]>,
        "name": <str>,
        "release_date": <str>,
        "release_date_precision": <str>,
        "restrictions": {
          "reason": <str>
        },
        "resume_point": {
          "fully_played": <bool>,
          "resume_position_ms": <int>
        },
        "type": "chapter",
        "uri": <str>
      }
    ],
    "limit": <int>,
    "next": <str>,
    "offset": <int>,
    "previous": <str>,
    "total": <int>
  },
  "copyrights": [
    {
      "text": <str>,
      "type": <str>
    }
  ],
  "description": <str>,
  "edition": <str>,
  "explicit": <bool>,
  "external_urls": {
    "spotify": <str>
  },
  "href": <str>,
  "html_description": <str>,
  "id": <str>,
  "images": [
    {
      "height": <int>,
      "url": <str>,
      "width": <int>
    }
  ],
  "languages": [
    <str>
  ],
  "media_type": <str>,
  "name": <str>,
  "narrators": [
    {
      "name": <str>
    }
  ],
  "publisher": <str>,
  "total_chapters": <int>,
  "type": "audiobook",
  "uri": <str>
}

{
  "audiobooks": [
    {
      "authors": [
        {
          "name": <str>
        }
      ],
      "available_markets": <list[str]>,
      "chapters": {
        "href": <str>,
        "items": [
          {
            "audio_preview_url": <str>,
            "available_markets": <list[str]>,
            "chapter_number": <int>,
            "description": <str>,
            "duration_ms": <int>,
            "explicit": <bool>,
            "external_urls": {
              "spotify": <str>
            },
            "href": <str>,
            "html_description": <str>,
            "id": <str>,
            "images": [
              {
                "height": <int>,
                "url": <str>,
                "width": <int>
              }
            ],
            "is_playable": <bool>,
            "languages": <list[str]>,
            "name": <str>,
            "release_date": <str>,
            "release_date_precision": <str>,
            "restrictions": {
              "reason": <str>
            },
            "resume_point": {
              "fully_played": <bool>,
              "resume_position_ms": <int>
            },
            "type": "chapter",
            "uri": <str>
          }
        ],
        "limit": <int>,
        "next": <str>,
        "offset": <int>,
        "previous": <str>,
        "total": <int>
      },
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "edition": <str>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "html_description": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "languages": <list[str]>,
      "media_type": <str>,
      "name": <str>,
      "narrators": [
        {
          "name": <str>
        }
      ],
      "publisher": <str>,
      "total_chapters": <int>,
      "type": "audiobook",
      "uri": <str>
    }
  ]
}
get_my_saved_audiobooks(*, country_code: str | None = None, limit: int | None = None, offset: int | None = None) → dict[str, Any][source]

Audiobooks > Get User’s Saved Audiobooks: Get Spotify catalog information for the audiobooks saved in the current user’s library.

Authorization scope

user-library-read scope

Access your saved content. Learn more.

Parameters:
country_codestr; keyword-only; optional

ISO 3166-1 alpha-2 country code. If provided, only content available in that market is returned. When a user access token accompanies the request, the country associated with the user account takes priority over this parameter.

Note

If neither a country code is provided nor a country can be determined from the user account, the content is considered unavailable for the client.

Example: "ES".

limitint; keyword-only; optional

Maximum number of audiobooks to return.

Valid range: 1 to 50.

API default: 20.

offsetint; keyword-only; optional

Index of the first audiobook to return. Use with limit to get the next batch of audiobooks.

Minimum value: 0.

API default: 0.

Returns:
audiobooksdict[str, Any]

Page of Spotify metadata for the user’s saved audiobooks.

Sample response

{
  "href": <str>,
  "items": [
    {
      "authors": [
        {
          "name": <str>
        }
      ],
      "available_markets": <list[str]>,
      "copyrights": [
        {
          "text": <str>,
          "type": <str>
        }
      ],
      "description": <str>,
      "edition": <str>,
      "explicit": <bool>,
      "external_urls": {
        "spotify": <str>
      },
      "href": <str>,
      "html_description": <str>,
      "id": <str>,
      "images": [
        {
          "height": <int>,
          "url": <str>,
          "width": <int>
        }
      ],
      "languages": <list[str]>,
      "media_type": <str>,
      "name": <str>,
      "narrators": [
        {
          "name": <str>
        }
      ],
      "publisher": <str>,
      "total_chapters": <int>,
      "type": "audiobook",
      "uri": <str>
    }
  ],
  "limit": <int>,
  "next": <str>,
  "offset": <int>,
  "previous": <str>,
  "total": <int>
}
remove_saved_audiobooks(audiobook_ids: str | Collection[str], /) → None[source]

Audiobooks > Remove User’s Saved Audiobooks: Remove one or more audiobooks from the current user’s library.

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

Parameters:
audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "18yVqkdbdRvS24c0Ilj2ci"

  • "18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"

  • ["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]

save_audiobooks(audiobook_ids: str | Collection[str], /) → None[source]

Audiobooks > Save Audiobooks for Current User: Save one or more audiobooks to the current user’s library.

Authorization scope

user-library-modify scope

Manage your saved content. Learn more.

Parameters:
audiobook_idsstr or Collection[str]; positional-only

Spotify IDs of the audiobooks. A maximum of 50 IDs can be sent in a request.

Examples:

  • "18yVqkdbdRvS24c0Ilj2ci"

  • "18yVqkdbdRvS24c0Ilj2ci,1HGw3J3NxZO1TP1BTtVhpZ"

  • ["18yVqkdbdRvS24c0Ilj2ci", "1HGw3J3NxZO1TP1BTtVhpZ"]