Chartmetric

#!/usr/bin/env python3
"""
Discover artists by filtering on metrics, geography, genre, and more.

This is the POWER endpoint - find artists matching specific criteria.

Usage:
    # Find US artists with 100K-500K Spotify monthly listeners
    python discover_artists.py --country US --spotify-listeners 100000 500000
    
    # Find TikTok-famous artists weak on Spotify (signing opportunity)
    python discover_artists.py --tiktok-followers 1000000 10000000 --spotify-listeners 0 100000
    
    # Find emerging hip-hop artists
    python discover_artists.py --genre 86 --spotify-listeners 50000 200000 --sort weekly_diff.sp_monthly_listeners
    
    # Find solo female artists in Brazil
    python discover_artists.py --country BR --band false --pronoun she/her
    
    # Find artists at a specific festival
    python discover_artists.py --festival-id 123

Metric Filters (use two values for [min, max]):
    --spotify-listeners     Spotify monthly listeners range
    --spotify-followers     Spotify followers range
    --spotify-popularity    Spotify popularity (0-100)
    --tiktok-followers      TikTok followers range
    --tiktok-likes          TikTok likes range
    --instagram-followers   Instagram followers range
    --youtube-subscribers   YouTube subscribers range
    --cpp                   Cross-Platform Performance score range

Other Filters:
    --country              2-letter country code (US, GB, BR, etc.)
    --genre                Genre ID (use list_genres.py to find IDs)
    --subgenre             Subgenre ID
    --band                 true/false - filter bands or solo artists
    --pronoun              he/him, she/her, they/them, any
    --first-release-days   Artists who debuted within X days
    --festival-id          Artists playing at specific festival

Sorting:
    --sort                 Sort column (default: latest.sp_monthly_listeners)
    --asc                  Sort ascending (default: descending)

Sort column format: <period>.<stat>
    Periods: latest, weekly_diff, monthly_diff
    Stats: sp_monthly_listeners, sp_followers, tt_followers, ig_followers, cpp, etc.

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import argparse
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def discover_artists(
    country: str = None,
    genre_id: int = None,
    subgenre_id: int = None,
    band: bool = None,
    pronoun: str = None,
    first_release_days: int = None,
    festival_ids: list = None,
    spotify_listeners: tuple = None,
    spotify_followers: tuple = None,
    spotify_popularity: tuple = None,
    tiktok_followers: tuple = None,
    tiktok_likes: tuple = None,
    instagram_followers: tuple = None,
    youtube_subscribers: tuple = None,
    cpp: tuple = None,
    sort_column: str = "latest.sp_monthly_listeners",
    sort_desc: bool = True,
    limit: int = 50,
    offset: int = 0
) -> dict:
    """
    Discover artists using Chartmetric's powerful filter endpoint.
    
    Returns artists matching the specified criteria with all their metrics.
    """
    token = get_token()
    
    params = {
        "limit": limit,
        "offset": offset,
        "sortColumn": sort_column,
        "sortOrderDesc": str(sort_desc).lower()
    }
    
    # Basic filters
    if country:
        params["code2"] = country
    if genre_id:
        params["tagId"] = genre_id
    if subgenre_id:
        params["subTagId"] = subgenre_id
    if band is not None:
        params["band"] = str(band).lower()
    if pronoun:
        params["pronoun"] = pronoun
    if first_release_days:
        params["firstReleaseDaysAgo"] = first_release_days
    if festival_ids:
        params["eventIds[]"] = festival_ids
    
    # Metric range filters (need special handling for arrays)
    range_params = []
    if spotify_listeners:
        range_params.append(("sp_ml[]", spotify_listeners[0]))
        range_params.append(("sp_ml[]", spotify_listeners[1]))
    if spotify_followers:
        range_params.append(("sp_f[]", spotify_followers[0]))
        range_params.append(("sp_f[]", spotify_followers[1]))
    if spotify_popularity:
        range_params.append(("sp_p[]", spotify_popularity[0]))
        range_params.append(("sp_p[]", spotify_popularity[1]))
    if tiktok_followers:
        range_params.append(("tt_f[]", tiktok_followers[0]))
        range_params.append(("tt_f[]", tiktok_followers[1]))
    if tiktok_likes:
        range_params.append(("tt_l[]", tiktok_likes[0]))
        range_params.append(("tt_l[]", tiktok_likes[1]))
    if instagram_followers:
        range_params.append(("ig_f[]", instagram_followers[0]))
        range_params.append(("ig_f[]", instagram_followers[1]))
    if youtube_subscribers:
        range_params.append(("ytc_s[]", youtube_subscribers[0]))
        range_params.append(("ytc_s[]", youtube_subscribers[1]))
    if cpp:
        range_params.append(("cpp[]", cpp[0]))
        range_params.append(("cpp[]", cpp[1]))
    
    # Build URL with array params
    url = f"{API_BASE}/artist/list/filter"
    
    response = requests.get(
        url,
        headers={"Authorization": f"Bearer {token}"},
        params=params if not range_params else None
    )
    
    # If we have range params, we need to build the URL manually
    if range_params:
        from urllib.parse import urlencode
        base_query = urlencode(params)
        range_query = "&".join([f"{k}={v}" for k, v in range_params])
        full_url = f"{url}?{base_query}&{range_query}"
        response = requests.get(
            full_url,
            headers={"Authorization": f"Bearer {token}"}
        )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 401:
        return {"error": "Unauthorized", "message": "This endpoint may require a higher subscription tier."}
    
    response.raise_for_status()
    return response.json()


def main():
    parser = argparse.ArgumentParser(
        description="Discover artists by filtering on metrics and attributes",
        formatter_class=argparse.RawDescriptionHelpFormatter
    )
    
    # Basic filters
    parser.add_argument("--country", "-c", help="2-letter country code (US, GB, BR)")
    parser.add_argument("--genre", "-g", type=int, help="Genre ID")
    parser.add_argument("--subgenre", type=int, help="Subgenre ID")
    parser.add_argument("--band", choices=["true", "false"], help="Filter bands or solo")
    parser.add_argument("--pronoun", choices=["any", "he/him", "she/her", "they/them"])
    parser.add_argument("--first-release-days", type=int, help="Debuted within X days")
    parser.add_argument("--festival-id", type=int, action="append", help="Festival event ID")
    
    # Metric ranges (2 values each)
    parser.add_argument("--spotify-listeners", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="Spotify monthly listeners range")
    parser.add_argument("--spotify-followers", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="Spotify followers range")
    parser.add_argument("--spotify-popularity", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="Spotify popularity range (0-100)")
    parser.add_argument("--tiktok-followers", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="TikTok followers range")
    parser.add_argument("--tiktok-likes", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="TikTok likes range")
    parser.add_argument("--instagram-followers", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="Instagram followers range")
    parser.add_argument("--youtube-subscribers", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="YouTube subscribers range")
    parser.add_argument("--cpp", type=int, nargs=2, metavar=("MIN", "MAX"),
                        help="Cross-Platform Performance score range")
    
    # Sorting and pagination
    parser.add_argument("--sort", default="latest.sp_monthly_listeners",
                        help="Sort column (default: latest.sp_monthly_listeners)")
    parser.add_argument("--asc", action="store_true", help="Sort ascending")
    parser.add_argument("--limit", "-l", type=int, default=50, help="Results limit")
    parser.add_argument("--offset", type=int, default=0, help="Pagination offset")
    parser.add_argument("--json", action="store_true", help="Output raw JSON")
    
    args = parser.parse_args()
    
    result = discover_artists(
        country=args.country,
        genre_id=args.genre,
        subgenre_id=args.subgenre,
        band=args.band == "true" if args.band else None,
        pronoun=args.pronoun,
        first_release_days=args.first_release_days,
        festival_ids=args.festival_id,
        spotify_listeners=tuple(args.spotify_listeners) if args.spotify_listeners else None,
        spotify_followers=tuple(args.spotify_followers) if args.spotify_followers else None,
        spotify_popularity=tuple(args.spotify_popularity) if args.spotify_popularity else None,
        tiktok_followers=tuple(args.tiktok_followers) if args.tiktok_followers else None,
        tiktok_likes=tuple(args.tiktok_likes) if args.tiktok_likes else None,
        instagram_followers=tuple(args.instagram_followers) if args.instagram_followers else None,
        youtube_subscribers=tuple(args.youtube_subscribers) if args.youtube_subscribers else None,
        cpp=tuple(args.cpp) if args.cpp else None,
        sort_column=args.sort,
        sort_desc=not args.asc,
        limit=args.limit,
        offset=args.offset
    )
    
    if args.json:
        print(json.dumps(result, indent=2))
        return
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    artists = result.get("obj", [])
    print(f"Found {len(artists)} artists:\n")
    
    for artist in artists[:30]:
        print(f"- {artist.get('name')}")
        print(f"  CM ID: {artist.get('id')}")
        
        # Show key metrics
        if artist.get('sp_monthly_listeners'):
            print(f"  Spotify Listeners: {artist.get('sp_monthly_listeners'):,}")
        if artist.get('sp_followers'):
            print(f"  Spotify Followers: {artist.get('sp_followers'):,}")
        if artist.get('tiktok_followers'):
            print(f"  TikTok Followers: {artist.get('tiktok_followers'):,}")
        if artist.get('ins_followers'):
            print(f"  Instagram Followers: {artist.get('ins_followers'):,}")
        if artist.get('code2'):
            print(f"  Country: {artist.get('code2')}")
        
        print()
    
    if len(artists) > 30:
        print(f"... and {len(artists) - 30} more (use --limit to adjust)")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Get artist's albums.

Usage:
    python get_artist_albums.py <chartmetric_id>
    python get_artist_albums.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_albums(cm_id: str) -> dict:
    """Fetch artist's albums from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/albums",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_albums.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_albums(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    albums = result.get("obj", [])
    print(f"Found {len(albums)} albums:\n")
    for album in albums[:20]:  # Limit to first 20
        print(f"- {album.get('name')}")
        print(f"  Chartmetric ID: {album.get('id')}")
        print(f"  Release: {album.get('release_date', 'N/A')}")
        print()

#!/usr/bin/env python3
"""
Get artist audience demographics for a platform.

Usage:
    python get_artist_audience.py <chartmetric_id> [--platform instagram]
    python get_artist_audience.py 3380
    python get_artist_audience.py 3380 --platform tiktok
    python get_artist_audience.py 3380 --platform youtube

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import argparse
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_audience(cm_id: str, platform: str = "instagram") -> dict:
    """Fetch artist audience demographics from Chartmetric."""
    token = get_token()
    
    endpoint_map = {
        "instagram": f"{API_BASE}/artist/{cm_id}/instagram-audience-stats",
        "tiktok": f"{API_BASE}/artist/{cm_id}/tiktok-audience-stats",
        "youtube": f"{API_BASE}/artist/{cm_id}/youtube-audience-stats",
    }
    
    url = endpoint_map.get(platform)
    if not url:
        return {"error": f"Unknown platform: {platform}", "valid_platforms": list(endpoint_map.keys())}
    
    response = requests.get(url, headers={"Authorization": f"Bearer {token}"})
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found or no audience data", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


def main():
    parser = argparse.ArgumentParser(description="Get artist audience demographics")
    parser.add_argument("chartmetric_id", help="Chartmetric artist ID")
    parser.add_argument("--platform", "-p", default="instagram",
                        choices=["instagram", "tiktok", "youtube"],
                        help="Platform for audience data")
    
    args = parser.parse_args()
    result = get_artist_audience(args.chartmetric_id, args.platform)
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Lookup artist by Spotify ID or URL.

Usage:
    python get_artist_by_spotify.py <spotify_id>
    python get_artist_by_spotify.py 3TVXtAsR1Inumwj472S9r4
    python get_artist_by_spotify.py "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4"

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import re
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def extract_spotify_id(url_or_id: str) -> str:
    """Extract Spotify artist ID from URL or return as-is if already an ID."""
    # If it looks like a URL, extract the ID
    match = re.search(r"artist[/:]([a-zA-Z0-9]+)", url_or_id)
    if match:
        return match.group(1)
    return url_or_id


def get_artist_by_spotify(spotify_id: str) -> dict:
    """Lookup Chartmetric artist by Spotify ID.
    
    Uses the /artist/:type/:id/get-ids endpoint to lookup artist by platform ID.
    Returns the Chartmetric artist ID and other platform IDs.
    """
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/spotify/{spotify_id}/get-ids",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {
            "error": "Payment Required",
            "message": "Your Chartmetric API subscription may be expired or this endpoint requires a higher tier. Check your account at chartmetric.com or contact hi@chartmetric.com"
        }
    
    if response.status_code == 404:
        return {"error": "Artist not found in Chartmetric", "spotify_id": spotify_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_by_spotify.py <spotify_id_or_url>")
        sys.exit(1)
    
    spotify_id = extract_spotify_id(sys.argv[1])
    result = get_artist_by_spotify(spotify_id)
    print(json.dumps(result, indent=2))

#!/usr/bin/env python3
"""
Get artist career history.

Usage:
    python get_artist_career.py <chartmetric_id>
    python get_artist_career.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_career(cm_id: str) -> dict:
    """Fetch artist career history from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/career",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_career.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_career(sys.argv[1])
    print(json.dumps(result, indent=2))

#!/usr/bin/env python3
"""
Get cities where people listen to an artist (Spotify data).

Usage:
    python get_artist_cities.py <chartmetric_id>
    python get_artist_cities.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_cities(cm_id: str) -> dict:
    """Fetch where people listen data from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/where-people-listen",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_cities.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_cities(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    cities_data = result.get("obj", {}).get("cities", {})
    print(f"Top cities for this artist:\n")
    
    # Get latest listener count for each city
    city_latest = []
    for city_name, history in cities_data.items():
        if history and len(history) > 0:
            latest = history[-1]  # Most recent data point
            city_latest.append({
                "name": city_name,
                "country": latest.get("code2", ""),
                "listeners": latest.get("listeners", 0)
            })
    
    # Sort by listeners descending
    city_latest.sort(key=lambda x: x.get("listeners", 0), reverse=True)
    
    for city in city_latest[:20]:
        print(f"- {city.get('name', 'Unknown')}, {city.get('country', '')}")
        print(f"  Listeners: {city.get('listeners', 0):,}")
        print()

#!/usr/bin/env python3
"""
Get AI-generated noteworthy insights for an artist.

Usage:
    python get_artist_insights.py <chartmetric_id>
    python get_artist_insights.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_insights(cm_id: str) -> dict:
    """Fetch noteworthy insights from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/noteworthy-insights",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_insights.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_insights(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    insights = result.get("obj", [])
    print(f"Noteworthy Insights:\n")
    for insight in insights:
        print(f"• {insight.get('text', insight)}")
        print()

#!/usr/bin/env python3
"""
Get artist's top Instagram posts and reels.

Usage:
    python get_artist_instagram_posts.py <chartmetric_id>
    python get_artist_instagram_posts.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_instagram_posts(cm_id: str) -> dict:
    """Fetch artist's top Instagram posts and reels."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/SNS/deepSocial/cm_artist/{cm_id}/instagram",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found or no Instagram data", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_instagram_posts.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_instagram_posts(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    print(json.dumps(result, indent=2))

#!/usr/bin/env python3
"""
Get artist metrics from a specific platform.

Usage:
    python get_artist_metrics.py <chartmetric_id> --source spotify
    python get_artist_metrics.py 3380 -s youtube_channel
    python get_artist_metrics.py 3380 -s instagram

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

Note: Use 'youtube_channel' or 'youtube_artist', NOT 'youtube'

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import json
import argparse
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"

VALID_SOURCES = [
    "spotify",
    "instagram",
    "tiktok",
    "twitter",
    "facebook",
    "youtube_channel",
    "youtube_artist",
    "soundcloud",
    "deezer",
    "twitch",
    "line",
    "melon",
    "wikipedia",
    "bandsintown",
]


def get_artist_metrics(cm_id: str, source: str) -> dict:
    """Fetch artist metrics for a specific platform."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/stat/{source}",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {
            "error": "Payment Required",
            "message": "Your Chartmetric API subscription may be expired or this endpoint requires a higher tier. Check your account at chartmetric.com or contact hi@chartmetric.com"
        }
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


def main():
    parser = argparse.ArgumentParser(description="Get artist metrics for a platform")
    parser.add_argument("chartmetric_id", help="Chartmetric artist ID")
    parser.add_argument(
        "--source", "-s", 
        required=True, 
        choices=VALID_SOURCES,
        help="Platform source"
    )
    
    args = parser.parse_args()
    result = get_artist_metrics(args.chartmetric_id, args.source)
    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Get artist playlist placements.

Usage:
    # Basic usage
    python get_artist_playlists.py <chartmetric_id>
    python get_artist_playlists.py 3380 --platform spotify --status current
    python get_artist_playlists.py 3380 --platform applemusic --status past
    
    # With filters (Spotify)
    python get_artist_playlists.py 3380 --editorial --newMusicFriday
    python get_artist_playlists.py 3380 --chart --indie
    
    # With date range and sorting
    python get_artist_playlists.py 3380 --since 2025-01-01 --sort followers --limit 50

Platforms: spotify, applemusic, deezer, amazon, youtube
Status: current, past

Spotify filters: editorial, personalized, chart, thisIs, newMusicFriday, radio,
                 fullyPersonalized, brand, majorCurator, popularIndie, indie, audiobook
                 
Apple Music filters: editorial, editorialBrand, chart, radio, musicBrand,
                     nonMusicBrand, indie, personalityArtist
                     
Deezer filters: editorial, deezerPartner, chart, hundredPercent, brand,
                majorCurator, popularIndie, indie

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import argparse
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"

# Platform-specific filter support
PLATFORM_FILTERS = {
    "spotify": ["editorial", "personalized", "chart", "thisIs", "newMusicFriday",
                "radio", "fullyPersonalized", "brand", "majorCurator", 
                "popularIndie", "indie", "audiobook"],
    "applemusic": ["editorial", "editorialBrand", "chart", "radio", "musicBrand",
                   "nonMusicBrand", "indie", "personalityArtist"],
    "deezer": ["editorial", "deezerPartner", "chart", "hundredPercent", "brand",
               "majorCurator", "popularIndie", "indie"],
    "amazon": [],  # No filters for Amazon
    "youtube": []  # No filters for YouTube
}


def get_artist_playlists(
    cm_id: str,
    platform: str = "spotify",
    status: str = "current",
    since: str = None,
    until: str = None,
    limit: int = 50,
    offset: int = 0,
    sort_column: str = None,
    sort_desc: bool = True,
    filters: dict = None
) -> dict:
    """
    Fetch artist playlist placements from Chartmetric.
    
    Args:
        cm_id: Chartmetric artist ID
        platform: spotify, applemusic, deezer, amazon, youtube
        status: current or past
        since: Start date (YYYY-MM-DD)
        until: End date (YYYY-MM-DD)
        limit: Results per page
        offset: Pagination offset
        sort_column: Column to sort by
        sort_desc: Sort descending
        filters: Dict of boolean filters (editorial, indie, etc.)
    """
    token = get_token()
    
    params = {"limit": limit}
    
    if offset > 0:
        params["offset"] = offset
    if since:
        params["since"] = since
    if until:
        params["until"] = until
    if sort_column:
        params["sortColumn"] = sort_column
        # Only include sortOrderDesc when explicitly sorting
        if not sort_desc:  # API defaults to descending, so only set when ascending
            params["sortOrderDesc"] = "false"
    
    # Add filter parameters
    if filters:
        for key, value in filters.items():
            if key in PLATFORM_FILTERS.get(platform, []):
                params[key] = str(value).lower()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/{platform}/{status}/playlists",
        headers={"Authorization": f"Bearer {token}"},
        params=params
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 401:
        return {"error": "Unauthorized", "message": "This endpoint may require a higher subscription tier."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


def main():
    parser = argparse.ArgumentParser(
        description="Get artist playlist placements",
        formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("chartmetric_id", help="Chartmetric artist ID")
    parser.add_argument("--platform", "-p", default="spotify",
                        choices=["spotify", "applemusic", "deezer", "amazon", "youtube"],
                        help="Playlist platform (default: spotify)")
    parser.add_argument("--status", "-s", default="current",
                        choices=["current", "past"],
                        help="Current or past placements (default: current)")
    
    # Date and pagination
    parser.add_argument("--since", help="Start date (YYYY-MM-DD)")
    parser.add_argument("--until", help="End date (YYYY-MM-DD)")
    parser.add_argument("--limit", "-l", type=int, default=50, help="Results limit")
    parser.add_argument("--offset", type=int, default=0, help="Pagination offset")
    parser.add_argument("--sort", help="Sort column (followers, added_at, name, etc.)")
    parser.add_argument("--asc", action="store_true", help="Sort ascending (default: descending)")
    
    # Filter flags (all platforms)
    parser.add_argument("--editorial", action="store_true", help="Editorial playlists")
    parser.add_argument("--chart", action="store_true", help="Chart playlists")
    parser.add_argument("--indie", action="store_true", help="Indie curator playlists")
    parser.add_argument("--radio", action="store_true", help="Radio playlists")
    parser.add_argument("--brand", action="store_true", help="Brand playlists")
    parser.add_argument("--majorCurator", action="store_true", help="Major curator playlists")
    parser.add_argument("--popularIndie", action="store_true", help="Popular indie playlists")
    
    # Spotify-specific filters
    parser.add_argument("--personalized", action="store_true", help="Personalized (Spotify)")
    parser.add_argument("--thisIs", action="store_true", help="This Is playlists (Spotify)")
    parser.add_argument("--newMusicFriday", action="store_true", help="New Music Friday (Spotify)")
    parser.add_argument("--fullyPersonalized", action="store_true", help="Fully personalized (Spotify)")
    parser.add_argument("--audiobook", action="store_true", help="Audiobook playlists (Spotify)")
    
    # Apple Music filters
    parser.add_argument("--editorialBrand", action="store_true", help="Editorial brand (Apple)")
    parser.add_argument("--musicBrand", action="store_true", help="Music brand (Apple)")
    parser.add_argument("--nonMusicBrand", action="store_true", help="Non-music brand (Apple)")
    parser.add_argument("--personalityArtist", action="store_true", help="Personality/artist (Apple)")
    
    # Deezer filters
    parser.add_argument("--deezerPartner", action="store_true", help="Deezer partner")
    parser.add_argument("--hundredPercent", action="store_true", help="100% playlists (Deezer)")
    
    args = parser.parse_args()
    
    # Build filters dict from args
    filter_names = ["editorial", "chart", "indie", "radio", "brand", "majorCurator",
                    "popularIndie", "personalized", "thisIs", "newMusicFriday",
                    "fullyPersonalized", "audiobook", "editorialBrand", "musicBrand",
                    "nonMusicBrand", "personalityArtist", "deezerPartner", "hundredPercent"]
    
    filters = {}
    for name in filter_names:
        if getattr(args, name, False):
            filters[name] = True
    
    result = get_artist_playlists(
        args.chartmetric_id,
        platform=args.platform,
        status=args.status,
        since=args.since,
        until=args.until,
        limit=args.limit,
        offset=args.offset,
        sort_column=args.sort,
        sort_desc=not args.asc,
        filters=filters if filters else None
    )
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    placements = result.get("obj", [])
    print(f"Found {len(placements)} playlist placements:\n")
    
    for item in placements[:20]:
        pl = item.get("playlist", {})
        track = item.get("track", {})
        print(f"- {pl.get('name', 'Unknown')}")
        print(f"  Track: {track.get('name', 'Unknown')}")
        
        position = pl.get('position', 'N/A')
        peak = pl.get('peak_position', 'N/A')
        print(f"  Position: {position} (Peak: {peak})")
        
        followers = pl.get('followers')
        if followers:
            print(f"  Followers: {followers:,}")
        
        print(f"  Added: {pl.get('added_at', 'N/A')}")
        
        if args.status == 'past' and pl.get('removed_at'):
            print(f"  Removed: {pl.get('removed_at')}")
        
        curator = pl.get('curator_name', 'Unknown')
        print(f"  Owner: {curator}")
        print()
    
    if len(placements) > 20:
        print(f"... and {len(placements) - 20} more (use --limit to adjust)")


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Get artist's tracks.

Usage:
    python get_artist_tracks.py <chartmetric_id>
    python get_artist_tracks.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_tracks(cm_id: str) -> dict:
    """Fetch artist's tracks from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/tracks",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_tracks.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_tracks(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    tracks = result.get("obj", [])
    print(f"Found {len(tracks)} tracks:\n")
    for track in tracks[:20]:  # Limit to first 20
        print(f"- {track.get('name')}")
        print(f"  Chartmetric ID: {track.get('id')}")
        print(f"  Album: {track.get('album_names', ['N/A'])[0] if track.get('album_names') else 'N/A'}")
        print()

#!/usr/bin/env python3
"""
Get artist's social and streaming service URLs.

Usage:
    python get_artist_urls.py <chartmetric_id>
    python get_artist_urls.py 3380

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist_urls(cm_id: str) -> dict:
    """Fetch artist's social/streaming URLs from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}/urls",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist_urls.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist_urls(sys.argv[1])
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    urls = result.get("obj", [])
    print("Artist URLs:\n")
    
    # Handle both list and dict formats
    if isinstance(urls, list):
        for item in urls:
            if isinstance(item, dict):
                domain = item.get("domain", "unknown")
                url = item.get("url", "")
                if url:
                    print(f"- {domain}: {url}")
            else:
                print(f"- {item}")
    elif isinstance(urls, dict):
        for platform, url in urls.items():
            if url:
                print(f"- {platform}: {url}")

#!/usr/bin/env python3
"""
Get artist profile by Chartmetric ID.

Usage:
    python get_artist.py <chartmetric_id>
    python get_artist.py 1234567

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import json
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_artist(cm_id: str) -> dict:
    """Fetch artist profile from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/artist/{cm_id}",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {
            "error": "Payment Required",
            "message": "Your Chartmetric API subscription may be expired or this endpoint requires a higher tier. Check your account at chartmetric.com or contact hi@chartmetric.com"
        }
    
    if response.status_code == 404:
        return {"error": "Artist not found", "chartmetric_id": cm_id}
    
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage: python get_artist.py <chartmetric_id>")
        sys.exit(1)
    
    result = get_artist(sys.argv[1])
    print(json.dumps(result, indent=2))

#!/usr/bin/env python3
"""
Get curator/playlist owner information.

Usage:
    python get_curator.py <curator_id> [--platform spotify]
    python get_curator.py 1
    python get_curator.py 1 --platform spotify

Environment:
    CHARTMETRIC_REFRESH_TOKEN - Your Chartmetric refresh token
"""

import sys
import argparse
import requests
from get_token import get_token

API_BASE = "https://api.chartmetric.com/api"


def get_curator(curator_id: str, platform: str = "spotify") -> dict:
    """Fetch curator info from Chartmetric."""
    token = get_token()
    
    response = requests.get(
        f"{API_BASE}/curator/{platform}/{curator_id}",
        headers={"Authorization": f"Bearer {token}"}
    )
    
    if response.status_code == 402:
        return {"error": "Payment Required", "message": "Check your Chartmetric subscription."}
    
    if response.status_code == 401:
        return {"error": "Unauthorized", "message": "This endpoint may require a higher subscription tier."}
    
    if response.status_code == 400:
        return {"error": "Bad Request", "message": "Curator ID must be a numeric Chartmetric ID."}
    
    if response.status_code == 404:
        return {"error": "Curator not found", "curator_id": curator_id}
    
    response.raise_for_status()
    return response.json()


def main():
    parser = argparse.ArgumentParser(description="Get curator information")
    parser.add_argument("curator_id", help="Chartmetric curator ID (numeric)")
    parser.add_argument("--platform", "-p", default="spotify",
                        choices=["spotify"],
                        help="Curator platform (currently only spotify supported)")
    
    args = parser.parse_args()
    result = get_curator(args.curator_id, args.platform)
    
    if "error" in result:
        print(f"Error: {result.get('error')}")
        if "message" in result:
            print(result.get('message'))
        sys.exit(1)
    
    curator = result.get("obj", {})
    print(f"Curator: {curator.get('name', 'Unknown')}")
    print(f"  Chartmetric ID: {curator.get('id')}")
    print(f"  User ID: {curator.get('user_id')}")
    if curator.get('image_url'):
        print(f"  Image: {curator.get('image_url')}")
    if curator.get('num_playlists'):
        print(f"  Playlists: {curator.get('num_playlists')}")
    if curator.get('followers'):
        print(f"  Followers: {curator.get('followers'):,}")


if __name__ == "__main__":
    main()