Songstats Python SDK

Official Python client for the Songstats Enterprise API.

📚 API Documentation: https://developers.stats.company/songstats
🔑 API Key Access: Please contact api@songstats.com

---

Requirements

• Python >= 3.10

---

Installation

Install from PyPI:

pip install songstats-sdk

For local development:

pip install -e ".[dev]"

---

Quick Start

fromsongstats_sdkimportSongstatsClientclient=SongstatsClient(api_key="YOUR_API_KEY")
# API statusstatus=client.info.status()
# Track informationtrack=client.tracks.info(songstats_track_id="abcd1234")
# Artist statisticsartist_stats=client.artists.stats(
songstats_artist_id="abcd1234",
source="spotify",
)

---

Authentication

All requests include your API key in the apikey header.

You can generate an API key in your Songstats Enterprise dashboard.

We recommend storing your key securely in environment variables:

export SONGSTATS_API_KEY=your_key_here

---

Available Resource Clients

• client.info
• client.tracks
• client.artists
• client.collaborators
• client.labels

Info endpoints:

• client.info.sources() -> /sources
• client.info.status() -> /status
• client.info.definitions() -> /definitions

---

Error Handling

fromsongstats_sdkimportSongstatsAPIError, SongstatsTransportErrortry:
client.tracks.info(songstats_track_id="invalid")
exceptSongstatsAPIErrorasexc:
print(f"API error: {exc}")
exceptSongstatsTransportErrorasexc:
print(f"Transport error: {exc}")

---

Development

To work on the SDK locally:

git clone https://github.com/songstats/songstats-python-sdk.git
cd songstats-python-sdk
pip install -e ".[dev]"
pytest

---

Versioning

This SDK follows Semantic Versioning (SemVer).

---

License

MIT