Radio Paradise APIradioparadise.com ↗
Access Radio Paradise live playback data, playlist history, song details, ratings, comments, and stream URLs across all 8 channels via a structured REST API.
What is the Radio Paradise API?
The Radio Paradise API exposes 9 endpoints covering live playback state, song metadata, playlist history, user comments, and stream links across all Radio Paradise channels. The get_now_playing endpoint returns the current track's artist, title, album, release year, and cover art URL in real time, while get_song_details surfaces full lyrics, artist biography HTML, and ratings distributions for any song ID in the catalog.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/54ed1a7f-b720-41fd-9dac-1d58567b969d/list_channels' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace radioparadise-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Radio Paradise SDK — browse channels, check now playing, explore song details and history."""
from parse_apis.radio_paradise_api import RadioParadise, ChannelId, SongNotFound
client = RadioParadise()
# List all channels and print their names + listener counts.
for channel in client.channels.list(limit=5):
print(channel.title, channel.current_listeners)
# Construct a channel by ID and check what's currently playing.
main = client.channel(ChannelId.MAIN_MIX)
now = main.now_playing()
print(now.artist, "-", now.title, f"({now.album}, {now.year})")
# Get recent playlist history, then fetch older tracks via history_more.
hist = main.history()
for track in hist.song[:3]:
print(track.artist, "-", track.title, track.duration)
older = main.history_more(offset=hist.song[0].event)
print("Older track:", older.song[0].artist, "-", older.song[0].title)
# Look up a song by ID and read its comments.
try:
song = client.songs.get(song_id=hist.song[0].song_id)
print(song.artist, song.title, "—", song.total_comments, "comments")
page = song.comments()
for c in page.comments[:3]:
print(f" {c.username}: {c.message[:60]}… (+{c.upvotes}/-{c.downvotes})")
except SongNotFound as exc:
print(f"Song not found: {exc}")
# Get stream URLs for all channels.
streams = client.streamcollections.list()
for link in streams.stream_links[:2]:
print(link.channel, link.links[0].bitrate, link.links[0].url)
print("Exercised: channels.list / now_playing / history / history_more / songs.get / song.comments / streamcollections.list")
Get all Radio Paradise channels with basic metadata. Returns channel IDs, names, slugs, current listener counts, stream URLs, cover images, and player configuration. The response contains an items array of all active channels.
No input parameters required.
{
"type": "object",
"fields": {
"items": "array of channel objects with chan, title, slug, stream_name, type, current_listeners, player_type, image"
},
"sample": {
"data": {
"items": [
{
"chan": "0",
"slug": "main-mix",
"type": "block",
"image": "https://img.radioparadise.com/channels/0/0/cover_512x512/0.jpg",
"title": "The Main Mix",
"player_type": "gapless-playlist",
"stream_name": "main-mix",
"current_listeners": "5752"
}
]
},
"status": "success"
}
}About the Radio Paradise API
Channels and Live Playback
The list_channels endpoint returns all Radio Paradise channels — Main Mix, Mellow, Rock, Global, Beyond, Serenity, KFAT, and Radio 2050 — with their channel_id, slug, current_listeners, stream_name, and player configuration fields like player_type. The get_now_playing endpoint accepts a channel_id parameter and returns the live track's artist, title, album, year, time (duration in seconds), and a cover image URL. get_channel_details adds CMS-level metadata per channel including channel_color, summary, banner, and DJ biography text.
Song Data and Ratings
get_song_info returns a mid-detail view for the currently playing track on a given channel: song_id, avg_rating, num_ratings, length formatted as M:SS, and a lyrics_avail flag. For deeper lookup, get_song_details accepts a numeric song_id and returns the full lyrics as an HTML string, wiki_html with artist biography content, release_date, avg_rating as a number, and ratings_num. Song IDs obtained from playlist history or now-playing responses can be passed directly into this endpoint.
Playlist History and Pagination
get_playlist_history returns the last several tracks played on a channel as a song array, with each entry containing event, song_id, artist, title, album, duration, and rating. The cover_base_url field lets you construct full cover image URLs for each track. For older history, pass the event field value from any track as the offset parameter to get_playlist_history_more to retrieve the next batch of earlier plays.
Comments and Stream Links
get_song_comments returns up to 20 comments per request for a given song_id, sorted by most_popular. Each comment object includes username, message, upvotes, downvotes, and posted_time. A more_offset field and more_comments boolean support pagination through a full comment thread. get_stream_links returns static stream URLs for every channel across AAC, MP3, Ogg Vorbis, and FLAC formats with associated bitrates, requiring no input parameters.
The Radio Paradise API is a managed, monitored endpoint for radioparadise.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when radioparadise.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official radioparadise.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Display the currently playing track and cover art on a custom Radio Paradise dashboard using
get_now_playing - Build a playlist replay log by paginating through
get_playlist_historyandget_playlist_history_morewith event-based offsets - Show song ratings and listener counts alongside lyrics retrieved from
get_song_details - Embed stream links from
get_stream_linksinto a media player supporting multiple audio formats and bitrates - Render per-channel metadata like theme color and DJ bio from
get_channel_detailsto style a channel-switching UI - Aggregate top-voted user comments for recently played songs using
get_song_commentswith pagination - Monitor live listener counts across all channels by polling
list_channelsfor thecurrent_listenersfield
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Radio Paradise have an official developer API?+
What does `get_playlist_history_more` require, and how does pagination work?+
offset parameter, which must be the event field value from a track returned by a previous get_playlist_history or get_playlist_history_more response. Each call returns an older batch of tracks for the specified channel_id. There is no page number system — pagination is entirely event-ID driven.Are song search or catalog browse endpoints available?+
song_id, but does not include a search endpoint or a way to browse the full song catalog. You can fork this API on Parse and revise it to add a search endpoint.Does `get_song_details` always return lyrics?+
get_song_info endpoint exposes a lyrics_avail flag that indicates whether lyrics exist for the current track. When lyrics_avail is false, the lyrics field in get_song_details may be empty or absent. The API reflects what Radio Paradise has on record for each song.Is there an endpoint for individual user profiles or rating history?+
avg_rating and num_ratings/ratings_num — at the song level, and per-comment upvotes and downvotes, but does not cover individual listener accounts or their personal rating histories. You can fork this API on Parse and revise it to add a user profile endpoint.