Chartmetric API

Music industry analytics via Python scripts. Get streaming metrics, playlist placements, audience data, and competitive insights.

Setup

With Python (recommended)

cd .recoup/skills/chartmetric
python3 -m venv .venv && source .venv/bin/activate
pip install requests
export CHARTMETRIC_REFRESH_TOKEN="your_token"

Without Python (curl fallback)

If Python is unavailable, see references/curl-fallback.md for curl-only patterns. Only requires curl (universal).

Quick Start

# 1. Search for an artist
python scripts/search_artist.py "Drake"
# Returns: Chartmetric ID 3380

# 2. Get profile and stats
python scripts/get_artist.py 3380
python scripts/get_artist_metrics.py 3380 --source spotify

# 3. Get where fans listen
python scripts/get_artist_cities.py 3380

Critical Gotchas

These are the API traps that cause 401/400 errors. Memorize them:

Scripts Reference

Artist Discovery

# Find US artists with 100K-500K Spotify monthly listeners
python scripts/discover_artists.py --country US --spotify-listeners 100000 500000

# TikTok-famous but weak on Spotify
python scripts/discover_artists.py --tiktok-followers 1000000 10000000 --spotify-listeners 0 100000

# Emerging artists in a genre, sorted by weekly growth
python scripts/discover_artists.py --genre 86 --spotify-listeners 50000 200000 --sort weekly_diff.sp_monthly_listeners

# Solo female artists in Brazil
python scripts/discover_artists.py --country BR --band false --pronoun she/her

# Festival performers with low Spotify (undervalued)
python scripts/discover_artists.py --festival-id 123 --spotify-followers 0 50000

Available filters: --country, --genre, --band, --pronoun, --spotify-listeners, --spotify-followers, --tiktok-followers, --instagram-followers, --youtube-subscribers, --cpp, --festival-id

Sort columns: latest.sp_monthly_listeners, weekly_diff.sp_monthly_listeners, monthly_diff.tt_followers, etc.

Search & Lookup

python scripts/search_artist.py "Taylor Swift"        # Search artists by name
python scripts/get_artist.py 2762                     # Get profile by CM ID
python scripts/get_artist_by_spotify.py 3TVXtAsR...   # Lookup by Spotify ID/URL
python scripts/get_track.py 128613854                 # Get track metadata
python scripts/get_track_by_spotify.py 0VjIjW4G...    # Lookup track by Spotify

Artist Data

python scripts/get_artist_albums.py 3380              # All albums
python scripts/get_artist_tracks.py 3380              # All tracks
python scripts/get_artist_cities.py 3380              # Top cities by listeners
python scripts/get_artist_urls.py 3380                # Social/streaming URLs
python scripts/get_artist_insights.py 3380            # AI-generated insights
python scripts/get_artist_career.py 3380              # Career timeline

Platform Metrics

python scripts/get_artist_metrics.py 3380 --source spotify
python scripts/get_artist_metrics.py 3380 --source instagram
python scripts/get_artist_metrics.py 3380 --source youtube_channel

Valid sources (14 total): spotify, instagram, tiktok, twitter, facebook, youtube_channel, youtube_artist, soundcloud, deezer, twitch, line, melon, wikipedia, bandsintown

Audience Demographics

python scripts/get_artist_audience.py 3380                        # Instagram (default)
python scripts/get_artist_audience.py 3380 --platform tiktok      # TikTok
python scripts/get_artist_audience.py 3380 --platform youtube     # YouTube
python scripts/get_artist_instagram_posts.py 3380                 # Top IG posts/reels

Playlist Placements

# Basic - current Spotify playlists
python scripts/get_artist_playlists.py 3380

# Other platforms
python scripts/get_artist_playlists.py 3380 --platform applemusic
python scripts/get_artist_playlists.py 3380 --platform deezer

# Past placements
python scripts/get_artist_playlists.py 3380 --status past

# With filters
python scripts/get_artist_playlists.py 3380 --editorial --newMusicFriday
python scripts/get_artist_playlists.py 3380 --indie --majorCurator

# With date range and sorting
python scripts/get_artist_playlists.py 3380 --since 2025-01-01 --sort followers --limit 100

Platforms: spotify, applemusic, deezer, amazon, youtube

Spotify filters: --editorial, --personalized, --chart, --thisIs, --newMusicFriday, --radio, --indie, --majorCurator, --popularIndie, --brand

Similar/Related Artists

# Basic related artists
python scripts/get_similar_artists.py 3380 --limit 10

# Advanced with configuration filters
python scripts/get_similar_artists.py 3380 --by-config --audience high --genre high
python scripts/get_similar_artists.py 3380 --by-config --mood medium --musicality high

Config options: --audience, --mood, --genre, --musicality (values: high, medium, low)

Playlists & Curators

python scripts/get_playlist.py spotify 37i9dQZF1DXcBWIGoYBM5M    # Playlist metadata
python scripts/get_curator.py 1                                  # Curator info (numeric ID)

Discovery

python scripts/list_genres.py                                    # All Chartmetric genres
python scripts/list_festivals.py                                 # Music festivals

Workflow Chains

Research an Artist for Playlist Pitching

# 1. Find the artist
python scripts/search_artist.py "Phoebe Bridgers"
# ID: 241089

# 2. Get their current playlist placements
python scripts/get_artist_playlists.py 241089 --editorial --limit 50

# 3. Find similar artists who might share playlists
python scripts/get_similar_artists.py 241089 --by-config --genre high --audience high

# 4. Check where their fans are
python scripts/get_artist_cities.py 241089
python scripts/get_artist_audience.py 241089 --platform instagram

Competitive Analysis

# 1. Get base artist
python scripts/get_artist.py 3380

# 2. Get similar artists with metrics
python scripts/get_similar_artists.py 3380 --by-config --audience high --limit 25

# 3. Compare streaming growth
python scripts/get_artist_metrics.py 3380 --source spotify
python scripts/get_artist_metrics.py <competitor_id> --source spotify

# 4. Compare playlist reach
python scripts/get_artist_playlists.py 3380 --sort followers
python scripts/get_artist_playlists.py <competitor_id> --sort followers

From Spotify URL to Full Profile

# 1. Convert Spotify URL to Chartmetric ID
python scripts/get_artist_by_spotify.py "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"
# Returns: cm_artist: 1320

# 2. Get everything
python scripts/get_artist.py 1320
python scripts/get_artist_metrics.py 1320 --source spotify
python scripts/get_artist_cities.py 1320
python scripts/get_artist_playlists.py 1320
python scripts/get_artist_audience.py 1320

More Advanced Workflows

See references/advanced-workflows.md for 10 strategic workflow chains including:

• Playlist pitching intelligence
• TikTok-to-Spotify pipeline analysis
• A&R discovery workflow
• Collaboration finder
• Viral song autopsy

References

Rate Limits

Chartmetric has rate limits. If you get 429 errors, wait 60 seconds before retrying.

Troubleshooting