# SHOUTcast Widgets Artist Library

> Free artist data API for internet radio and music projects: biographies, photos from every year since 2012, genres, facts and similar artists. No API key, CORS enabled.

Human docs: https://shoutcastwidgets.com/ArtistLibrary/
Artist pages: https://shoutcastwidgets.com/ArtistLibrary/?artist=Madonna

=== SHOUTcast Widgets Artist Library API ===
Free JSON API with artist biographies, photos, genres, facts and similar artists. No API key. CORS enabled.

ENDPOINT (use this one):
GET https://shoutcastwidgets.com/ArtistLibrary/v2/api/?artist={URL-encoded artist name}
Example: https://shoutcastwidgets.com/ArtistLibrary/v2/api/?artist=Guns%20N%27%20Roses

RESPONSE (JSON). Any field may be null; photo arrays may be empty:
- status: 1 = artist found, 0 = not found. If an "error" field is present, the request failed.
- displayName: correctly spelled name, e.g. "Guns N' Roses". name: upper-case cache key, e.g. "GUNS-N-ROSES".
- bioText: plain-text biography (paragraphs separated by blank lines). bio: the same text, URL-encoded.
- photos.large: array of {url, width, height, size, year}, oldest first. The LAST item is the newest photo.
- photos.small: same, thumbnails up to 150x150 px.
- tags, genres, similar: comma-separated strings, e.g. "Pop, Dance, Electropop".
- followers (Spotify followers), spotifyPopularity (0-100), stats (Last.fm listeners): integers or null.
- country, hometown, dob (birth date, or formation date for groups, "YYYY" or "YYYY-MM" or "YYYY-MM-DD"), gender (people only), title (short description), aka, mbid (MusicBrainz ID).
- spotifyUrl, lastFmUrl: links. Artist page for humans: https://shoutcastwidgets.com/ArtistLibrary/?artist={URL-encoded name}

EXAMPLE RESPONSE (shortened):
{"name":"MADONNA","displayName":"Madonna","status":1,
 "bioText":"Madonna Louise Ciccone (born August 16, 1958) is an American singer...",
 "photos":{"large":[{"url":"https://shoutcastwidgets.com/ArtistLibrary/Artists-2020/Big/MADONNA.webp","width":1024,"height":549,"size":102358,"year":2020},
                    {"url":"https://shoutcastwidgets.com/ArtistLibrary/Artists-2027/Big/MADONNA.JPG","width":1200,"height":900,"size":165236,"year":2027}],
           "small":[{"url":"https://shoutcastwidgets.com/ArtistLibrary/Artists-2027/Small/MADONNA.JPG","width":150,"height":112,"size":9354,"year":2027}]},
 "tags":"Pop, Dance, Electropop","genres":"Pop, Dance","similar":"Lady Gaga, Kylie Minogue, Cher",
 "country":"United States","dob":"1958-08-16","hometown":"Bay City","gender":"Female",
 "followers":8667651,"spotifyPopularity":82,"spotifyUrl":"https://open.spotify.com/artist/6tbjWDEIzxoDsBA1FuhfPW"}

HOW IT BEHAVES:
- The first lookup of an artist the library hasn't seen yet can take a few seconds: it is fetched from Last.fm, Spotify and MusicBrainz and saved permanently. Later lookups are instant. Every lookup helps grow the shared library.
- Use a 30-second timeout. Unknown artists return status 0 and are retried by the library after a day.

USAGE RULES:
- Cache results on your side (at least 24 hours for found artists, 1 hour for status 0). Never request the same artist more than once per hour.
- For bulk jobs, send at most 1 request every 2 seconds, one request at a time.
- Use the photo URLs directly (hotlinking is allowed) or download them for your own archive.
- Credit: biographies come from Last.fm (CC BY-SA). Show "Artist info: SHOUTcast Widgets Artist Library" linking to https://shoutcastwidgets.com/ArtistLibrary/

CLEANING NOW-PLAYING TITLES (radio metadata is usually "Artist - Title"):
- Split on the first " - " and trim; ignore titles without one, and station IDs, ads or jingles.
- For the main artist, cut at " feat.", " ft.", " featuring ", " x " or " vs." (case-insensitive).
- Keep "&" and punctuation in names (e.g. "Kool & the Gang", "P!nk", "AC/DC"); URL-encode the whole name.

LEGACY ENDPOINT (only if you need the original widget format):
GET https://shoutcastwidgets.com/ArtistLibrary/library/?artist={name}. photos.large/small are 4 strings relative to https://shoutcastwidgets.com/ArtistLibrary/ (2020, 2022, 2024, newest), bio is URL-encoded, plus absolute "image" and "thumbnail" URLs.

=== CODE EXAMPLES ===

--- JavaScript ---
async function getArtist(name) {
  const res = await fetch('https://shoutcastwidgets.com/ArtistLibrary/v2/api/?artist=' + encodeURIComponent(name));
  const artist = await res.json();
  if (artist.status !== 1) return null;               // not found
  return {
    name:   artist.displayName || name,
    photo:  artist.photos.large.at(-1)?.url,          // newest photo
    thumb:  artist.photos.small.at(-1)?.url,
    bio:    artist.bioText,
    genres: artist.genres,
  };
}

getArtist('Madonna').then(console.log);

--- PHP ---
function get_artist(string $name): ?array {
    $cache = sys_get_temp_dir() . '/artist_' . md5(strtolower($name)) . '.json';
    if (is_file($cache) && filemtime($cache) > time() - 86400) {
        $json = file_get_contents($cache);                       // cached for 24 hours
    } else {
        $url  = 'https://shoutcastwidgets.com/ArtistLibrary/v2/api/?artist=' . rawurlencode($name);
        $json = @file_get_contents($url, false, stream_context_create(['http' => ['timeout' => 30]]));
        if ($json === false) return null;
        file_put_contents($cache, $json);
    }
    $artist = json_decode($json, true);
    return ($artist['status'] ?? 0) === 1 ? $artist : null;
}

$a = get_artist('Madonna');
echo $a ? $a['displayName'] . ': ' . substr($a['bioText'], 0, 200) : 'Not found';

--- Python ---
import requests

def get_artist(name):
    r = requests.get("https://shoutcastwidgets.com/ArtistLibrary/v2/api/", params={"artist": name}, timeout=30)
    artist = r.json()
    return artist if artist.get("status") == 1 else None

a = get_artist("Madonna")
if a:
    print(a["displayName"], "|", a["genres"])
    if a["photos"]["large"]:
        print(a["photos"]["large"][-1]["url"])   # newest photo

--- cURL ---
curl "https://shoutcastwidgets.com/ArtistLibrary/v2/api/?artist=Guns%20N%27%20Roses"

# Legacy widget format
curl "https://shoutcastwidgets.com/ArtistLibrary/library/?artist=Madonna"

=== READY-MADE TASKS ===
If the user isn't sure what to build, suggest one of these:
- Now Playing artist card for my radio site: A self-contained widget that shows the current artist's photo, bio and genres and updates when the song changes.
- Save artist data for my whole music library: A script that looks up every artist you play and saves their data and photos locally. It also adds each artist to the shared library.
- WordPress plugin with an [artist_info] shortcode: Show any artist's photo, facts, bio and similar artists in posts and pages, cached on your server.
- Artist profile pages for my PHP website: artist.php?name=… pages with a photo gallery, bio, facts and links, plus SEO tags. Cached on disk.
- Use the library in my own project: A general prompt for anything else: apps, bots, spreadsheets, game shows, DJ tools. Describe your project and paste.