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 uv for virtualenv and dependency management. With uv installed:

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

uv sync --all-extras --dev

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

cp .env.example .env

3. Run the script in the virtual environment:

uv run appleconnector

To add a new dev dependency:

uv add --dev $package

To add a new runtime dependency:

uv add $package

Releasing

Releases are published to PyPI automatically by CI when a GitHub release is created. To cut a new release:

1. Bump the version field in pyproject.toml.

2. Commit and push to main.

3. Create a GitHub release with a matching vX.Y.Z tag — the deploy job will run uv build and upload the artifacts to PyPI.

To build the package locally:

uv build

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(2026, 10, 21), 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(2026, 10, 21), 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(2026, 10, 21), 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(*values)

Enum to represent a dimension for the Apple Podcasts API.

class appleconnector.Metric(*values)

Enum to represent a metric for the Apple Podcasts API.

class appleconnector.Mode(*values)

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

class appleconnector.SeriesMode(*values)

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