Apple Connector

Apple Connector

This is a simple library for connecting to the inofficial Apple podcast API. It can be used to export data from your dashboard at https://podcastsconnect.apple.com.

Supported Data

• Podcast Overview

• Trends

• Episodes Overview

• Episode Details

Credentials

We need the myacinfo and itctx cookies from your browser to authenticate. They can be found through the network tab in your browser’s developer tools. Add them to .env as MYACINFO and ITCTX. (You need to quote the values, as they may contain |.)

Installation

pip install appleconnector

Usage as a library

from appleconnector import AppleConnector

# Set up the connector
connector = AppleConnector(
    podcast_id='1642486726',
    myacinfo="your_myacinfo_cookie",
    itctx="your_itctx_cookie"
)

# Get Podcast overview data
connector.overview()

# ...

See __main.py__ for all endpoints.

Development

We use [Pipenv] for virtualenv and dev dependency management. With Pipenv installed:

1. Install your locally checked out code in [development mode], including its dependencies, and all dev dependencies into a virtual environment:

pipenv sync --dev

2. Create an environment file and fill in the required values:

cp .env.example .env

3. Run the script in the virtual environment, which will [automatically load your .env][env]:

pipenv run appleconnector

To add a new dependency for use during the development of this library:

pipenv install --dev $package

To add a new dependency necessary for the correct operation of this library, add the package to the install_requires section of ./setup.py, then:

pipenv install

To publish the package:

python setup.py sdist bdist_wheel
twine upload dist/*

or

make publish

API

This package allows you to fetch data from the inofficial Apple Podcast API. The API is not documented and may change at any time. Use at your own risk.

class appleconnector.AppleConnector(podcast_id, myacinfo, itctx)

Representation of the inofficial Apple podcast API.

episode(episode_id: str, start: date = datetime.datetime(2017, 9, 19, 0, 0), end: date = datetime.date(2024, 3, 14), mode: Mode = Mode.ALL_TIME) → dict

Episode details endpoint

Args:

episode_id (str): Apple Podcast Episode ID. start (dt.date): Start date. end (dt.date): End date. mode (Mode): Duration mode.

Returns:

dict: Response data from API.

episodes(date: date = datetime.datetime(2017, 9, 19, 0, 0), mode: Mode = Mode.ALL_TIME) → dict

Loads episode data for podcast.

Args:

date (dt.date): Date. mode (Mode): Duration mode.

Returns:

dict: Response data from API.

overview(start: date = datetime.datetime(2017, 9, 19, 0, 0), end: date = datetime.date(2024, 3, 14), mode: Mode = Mode.ALL_TIME, series_mode: SeriesMode = SeriesMode.MONTHLY) → dict

Loads overview data for podcast.

Args:

start (dt.date): Start date. end (dt.date): End date. mode (Mode): Duration mode. series_mode (SeriesMode): Series mode.

Returns:

dict: Response data from API.

trends(start: date = datetime.datetime(2017, 9, 19, 0, 0), end: date = datetime.date(2024, 3, 14), mode: Mode = Mode.ALL_TIME, series_mode: SeriesMode = SeriesMode.DAILY, metric: Metric = Metric.PLAYS, dimension: Dimension = Dimension.BY_COUNTRY) → dict

Loads trend data for podcast.

Daily metrics, 16 dimensions which can be even broke down further, (e.g. episode listens in Germany by engaged users)

Args:

start (dt.date): Start date. end (dt.date): End date. mode (Mode): Duration mode. series_mode (SeriesMode): Series mode. metric (Metric): Metric. Defaults to Metric.PLAYS. dimension (Dimension): Dimension. Defaults to Dimension.BY_COUNTRY.

Returns:

dict: Response data from API.

class appleconnector.Dimension(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum to represent a dimension for the Apple Podcasts API.

class appleconnector.Metric(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum to represent a metric for the Apple Podcasts API.

class appleconnector.Mode(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum for the different query duration modes available for the Apple Podcasts API.

class appleconnector.SeriesMode(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum for the different series modes available for the Apple Podcasts API.