getting_started.rst

Getting started

Introduction

If you are new to Audible, this is the place to begin. The goal of this tutorial is to get you set-up and rolling with Audible. I won't go into too much detail here, just some important basics.

First Audible device

Before you can communicate with the non-publicly Audible Api, you need to authorize (login) yourself to Amazon (or Audible) and register a new "virtual" Audible device. Please make sure to select the correct Audible marketplace. An overview about all known Audible marketplaces and associated country codes be found at :ref:`country_codes`.

import audible

# Authorize and register in one step
auth = audible.Authenticator.from_login(
    USERNAME,
    PASSWORD,
    locale=COUNTRY_CODE,
    with_username=False
)

# Save credentials to file
auth.to_file(FILENAME)

Important

Every device registration will be shown on the Amazon devices list. So only register once and reuse your authentication data or deregister the device with auth.deregister_device() before you close your session.

Note

If you have activated 2-factor-authentication for your Amazon account, you can append the current OTP to your password. This eliminates the need for a new OTP prompt.

Note

Set with_username=True to login with your pre-Amazon account (for US, UK or DE marketplace only).

Note

For security reasons in some cases you have to solve a Captcha and complete some extra steps. Please take a look at the :ref:`authorization` section for more information.

Hello Library

After the device creation was successfully completed, you are ready to make your first API call. To fetch and print out all books from your Audible library (sorted by purchase date in descending order) you can do:

with audible.Client(auth=auth) as client:
    library = client.get(
        "1.0/library",
        num_results=1000,
        response_groups="product_desc, product_attrs",
        sort_by="-PurchaseDate"
    )
    for book in library["items"]:
        print(book)

Note

The information returned by the API depends on the requested response_groups. The response for the example above are very minimized. Please take a look at :http:get:`/1.0/library` for all known response_groups and other parameter for the library endpoint.

Reuse authentication data

You can store your authentication data after an device registration with:

auth.to_file(FILENAME)

And load the data from file to reuse it with:

auth = audible.Authenticator.from_file(FILENAME)