podigeeconnector 0.4.1

Podigee Connector for Podcast Data

Podigee Connector

This is a simple library for connecting to the Podigee API.
It can be used to export data from your dashboard at https://app.podigee.com/analytics

Supported Endpoints

• /podcasts/{podcast_id}/analytics
• /podcasts/{podcast_id}/overview (with optional scope parameter for totals)
• /podcasts/{podcast_id}/analytics/episodes
• /episodes/{episode_id}/analytics

See __main__.py for all endpoints.

Credentials

This API supports three authentication methods:

1. Using the official API token. This option is preferred, but only available if you have a professional account.
2. Using Podigee username and password. Use this only if you don't have access to the API through your account.
3. Using a session cookie that you need to extract manually from your browser.

If possible, use option 1, the official API token, as it is the most secure and officially supported authentication method. Find more information on the different authentication methods below.

Using the official API token

from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_access_token=PODIGEE_ACCESS_TOKEN,
)

Using the session token

Alternatively, you can use a session token to log in:

from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_session_v5=PODIGEE_SESSION_V5,
)

Using username and password

Finally, you can also call the login endpoint with your username and password to log in:

from podigeeconnector import PodigeeConnector

connector = PodigeeConnector.from_credentials(
   base_url=BASE_URL,
   podcast_id=PODCAST_ID,
   username=USERNAME,
   password=PASSWORD,
)

Installation

pip install podigeeconnector

Usage as a library

from podigeeconnector import PodigeeConnector

connector = PodigeeConnector(
   base_url=BASE_URL,
   podigee_access_token=PODIGEE_ACCESS_TOKEN,
)

end = datetime.now()
start = end - timedelta(days=30)

podcast_analytics = connector.podcast_analytics(podcast_id, start, end)
logger.info("Podcast Analytics = {}", json.dumps(podcast_analytics, indent=4))

# Get totals with listeners and subscribers count
podcast_totals = connector.podcast_totals(podcast_id, start, end)
logger.info("Total Downloads: {}", podcast_totals.get("total_downloads"))
logger.info("Unique Listeners: {}", podcast_totals.get("unique_listeners_number"))

# Get total downloads for a specific episode
episode_total = connector.episode_total_downloads(episode_id, start, end)
logger.info("Episode Total Downloads: {}", episode_total)

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 in editable mode, including all runtime, dev, and optional dependencies, into a project-local .venv:

uv sync --all-extras --dev

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

cp .env.sample .env

3. Run the script (uv handles the virtualenv automatically):

uv run podigeeconnector

To add a new runtime dependency:

uv add $package

To add a new development-only dependency:

uv add --dev $package

To run linters, formatters, and tests:

make lint
make format-check
make test

Releasing

1. Bump the version field in pyproject.toml.
2. Commit and tag the release (git tag vX.Y.Z), then push the tag.
3. Create a GitHub release for the tag. CI will build (uv build) and publish sdist + wheel to PyPI via twine using the PYPI_API_TOKEN secret.

To build and publish manually:

make publish