If you're building tools or running analysis with music data, chances are you're using APIs to fetch information from platforms like Spotify, YouTube, or Apple. To make this easier, we’ve built an official Python SDK for the Soundcharts API!
But first — what is an SDK? A Software Development Kit is a set of tools, libraries, and documentation that makes it easier to work with an API. Our SDK handles things like authentication, pagination, rate limits, error handling, and response formatting — so you can focus on what matters: building.
Let’s walk through how to install and use it!
Prerequisites
To use the SDK, you'll need:
Python installed on your machine (Python 3.7+ recommended)
A Soundcharts API subscription with a valid app_id and api_key
Step 1 — Install the SDK
Open your terminal and install the SDK like any other Python module:
pip install soundcharts
Step 2 — Initialize the client and fetch artist metadata
To use the SDK, you'll need to initialize the client using your API Key and Token:
from soundcharts.client import SoundchartsClient
sc = SoundchartsClient(app_id="your_app_id", api_key="your_api_key")
And you're free to go! Let's start with a basic example: retrieving metadata for an artist.
# Example with Billie Eilish's UUID
billie_uuid = "11e81bcc-9c1c-ce38-b96b-a0369fe50396"
billie_metadata = sc.artist.get_artist_metadata(billie_uuid)
print(billie_metadata)
The SDK returns everything in JSON format, which you can easily parse:
print(billie_metadata["artist"]["name"])
Step 3 — Handling errors and logging
The SDK transparently handles error handling. If you hit a rate limit, use an invalid UUID, or run into quota issues, the SDK will raise an exception or log a message, depending on your setup.
You can control the log level for console, file, and exception logs:
from soundcharts.client import SoundchartsClient
import logging
sc = SoundchartsClient(app_id="your_app_id", api_key="your_api_key", console_log_level=logging.INFO, file_log_level=logging.WARNING, exception_log_level=logging.ERROR )
Set to DEBUG if you want to trace every API request.
Step 4 — Pagination and 90-day limits: looping made easy
The Soundcharts API often returns data in 90-day chunks or paginates results at 100 items per request. The SDK automatically handles that for you — no need to write loop logic yourself.
You can do this by specifying limit=None in endpoints with a pagination limit, or inputting any start_date and end_date you wish regardless of period length.
For example, to fetch radio spins over a full year:
spins = sc.radio.get_airplay(artist_uuid="11e81bcc-9c1c-ce38-b96b-a0369fe50396", radio_slug="skyrock", country_code="FR", start_date="2023-01-01", end_date="2023-12-31", limit = None)
The SDK will automatically loop over all 90-day periods and page through results until everything is retrieved.
❓ Need help or have suggestions? Feel free to reach out to us directly on help@soundcharts.com.