ChaptersAPI

class minim.api.spotify.ChaptersAPI(client: APIClient, /)

Bases: SpotifyResourceAPI

Chapters 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

get_chapters

Chapters > Get a Chapter: Get Spotify catalog information for an audiobook chapter․ Chapters > Get Several Chapters: Get Spotify catalog information for multiple audiobook chapters.

get_chapters(chapter_ids: str | Collection[str], /, *, country_code: str) → dict[str, Any]

Chapters > Get a Chapter: Get Spotify catalog information for an audiobook chapter․ Chapters > Get Several Chapters: Get Spotify catalog information for multiple audiobook chapters.

Third-party application mode

Optional

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:

chapter_idsstr or Collection[str]; positional-only

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

Examples:

• "0IsXVP0JmcB2adSE338GkK"

• "0IsXVP0JmcB2adSE338GkK,3ZXb8FKZGU0EHALYX6uCzU"

• ["0IsXVP0JmcB2adSE338GkK", "3ZXb8FKZGU0EHALYX6uCzU"]

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:

chaptersdict[str, Any]

Spotify metadata for the audiobook chapters.

Sample responses

Single audiobook chapter

{
  "audio_preview_url": <str>,
  "audiobook": {
    "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>
  },
  "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>
}

Multiple audiobook chapters

{
  "chapters": [
    {
      "audio_preview_url": <str>,
      "audiobook": {
        "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>
      },
      "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>
    }
  ]
}