Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jonathan343/spotify-sdk/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The AudiobookService (sync) and AsyncAudiobookService (async) provide methods for retrieving Spotify audiobook information and chapters.
Both sync and async versions are available. Import AudiobookService for sync operations or AsyncAudiobookService for async operations.

​
Methods

​
get

Retrieve detailed information about a single audiobook by its Spotify ID. 
async def get(id: str, market: str | None = None) -> Audiobook
​
id
str
required
The Spotify ID for the audiobook.
​
market
str | None
default:"None"
An ISO 3166-1 alpha-2 country code for availability. Audiobook availability varies by region.
Returns: Audiobook - The complete audiobook object with metadata including authors, narrators, and chapter information. Raises: ValueError if id is empty. 
from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_token") as client:
    audiobook = await client.audiobooks.get("7iHfbu1YPACw6oZPAFJtqe", market="US")
    
    print(f"Audiobook: {audiobook.name}")
    print(f"Authors: {', '.join([author.name for author in audiobook.authors])}")
    print(f"Narrators: {', '.join([narrator.name for narrator in audiobook.narrators])}")
    print(f"Publisher: {audiobook.publisher}")
    print(f"Total chapters: {audiobook.total_chapters}")
    print(f"Language: {audiobook.languages[0] if audiobook.languages else 'N/A'}")
Always specify a market code when working with audiobooks, as content availability varies significantly by region.

​
get_several

Retrieve multiple audiobooks in a single request. 
async def get_several(
    ids: list[str],
    market: str | None = None
) -> list[Audiobook]
​
ids
list[str]
required
List of Spotify audiobook IDs. Maximum of 50 IDs per request enforced by Spotify API.
​
market
str | None
default:"None"
An ISO 3166-1 alpha-2 country code for availability.
Returns: list[Audiobook] - List of audiobook objects. Raises: ValueError if ids is empty. 
from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_token") as client:
    audiobook_ids = [
        "7iHfbu1YPACw6oZPAFJtqe",
        "3VVFo7JEK3KoLNdJGXSJCH",
        "18yVqkdbdRvS24c0Ilj2ci"
    ]
    
    audiobooks = await client.audiobooks.get_several(audiobook_ids, market="US")
    
    for audiobook in audiobooks:
        authors = ', '.join([author.name for author in audiobook.authors])
        print(f"{audiobook.name} by {authors}")
        print(f"  Chapters: {audiobook.total_chapters}")
Batch requests are more efficient than multiple individual requests. The Spotify API allows up to 50 audiobooks per call.

​
get_chapters

Retrieve the chapters from a specific audiobook with pagination support. 
async def get_chapters(
    id: str,
    market: str | None = None,
    limit: int = 20,
    offset: int = 0
) -> Page[SimplifiedChapter]
​
id
str
required
The Spotify ID for the audiobook.
​
market
str | None
default:"None"
An ISO 3166-1 alpha-2 country code for availability.
​
limit
int
default:"20"
Maximum number of chapters to return. Valid range: 1-50.
​
offset
int
default:"0"
Index of the first chapter to return (for pagination).
Returns: Page[SimplifiedChapter] - Paginated response containing simplified chapter objects. Raises: ValueError if id is empty. 
from spotify_sdk import AsyncSpotifyClient

async with AsyncSpotifyClient(access_token="your_token") as client:
    chapters = await client.audiobooks.get_chapters(
        "7iHfbu1YPACw6oZPAFJtqe",
        market="US",
        limit=10
    )
    
    print(f"Total chapters: {chapters.total}")
    for chapter in chapters.items:
        duration_min = chapter.duration_ms // 60000
        duration_sec = (chapter.duration_ms % 60000) // 1000
        print(f"Chapter {chapter.chapter_number}: {chapter.name}")
        print(f"  Duration: {duration_min}:{duration_sec:02d}")
        print(f"  Description: {chapter.description[:100]}..." if chapter.description else "")
    
    # Pagination
    if chapters.next:
        next_chapters = await client.audiobooks.get_chapters(
            "7iHfbu1YPACw6oZPAFJtqe",
            market="US",
            limit=10,
            offset=10
        )
Chapter numbers and total counts help with navigation and displaying progress through an audiobook.
  • Audiobook - Full audiobook object with complete metadata
  • SimplifiedChapter - Chapter object with essential information
  • Page[T] - Paginated response wrapper

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us