Rate Your Music APIrateyourmusic.com ↗
Access RYM album ratings, artist discographies, genre hierarchies, and music charts via 7 structured endpoints. No account required.
What is the Rate Your Music API?
The Rate Your Music API exposes 7 endpoints covering album details, artist discographies, genre hierarchies, charts, and search across the RYM catalog. get_release_details returns a full tracklist with durations, primary and secondary genre classifications, descriptors, average rating, and rating count for any release. get_charts delivers paginated chart entries filterable by media type, chart type, and year range, making it straightforward to pull ranked lists of albums or tracks across any time period.
curl -X GET 'https://api.parse.bot/scraper/4543201b-0c81-4415-b1a4-83478db54412/get_charts?page=1&year=all-time&chart_type=top&media_type=album' \ -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 rateyourmusic-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.
"""Walkthrough: Rate Your Music SDK — bounded, re-runnable; every call capped."""
from parse_apis.Rate_Your_Music_API import RateYourMusic, SearchType, ChartType, MediaType, ParseError
client = RateYourMusic()
# Search for an artist
for result in client.search_results.search(query="Radiohead", search_type=SearchType.A, limit=3):
print(result.name, result.url, result.type)
# Get top chart entries
for entry in client.chart_entries.list(chart_type=ChartType.TOP, media_type=MediaType.ALBUM, year="all-time", limit=3):
print(entry.rank, entry.release_name, entry.artist, entry.rating)
# Fetch a release detail
release = client.releases.get(url="/release/album/kendrick-lamar/to-pimp-a-butterfly/")
print(release.title, release.artist, release.average_rating)
for track in release.tracklist[:3]:
print(track.num, track.name, track.duration)
print("Movements:", release.movements)
# Fetch a song's genre classification
song = client.songs.get(url="/song/john-mayer/in-your-atmosphere/")
print(song.title, song.artist, song.genres)
# Explore genres and get details on one
genre = client.genres.list(limit=1).first()
try:
detail = genre.details()
print(detail.name, detail.parents)
except ParseError as e:
print("error:", e.code)
print("exercised: search_results.search, chart_entries.list, releases.get, songs.get, genres.list, genre.details")
Extract charts data for albums or tracks. Returns paginated results with 40 items per page. Supports filtering by media type, chart type, and year.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-indexed). |
| year | string | Year or year range (e.g. 2024, 2020-2024, all-time). |
| chart_type | string | Type of chart. |
| media_type | string | Type of media. |
{
"type": "object",
"fields": {
"items": "array of chart entries with rank, release_name, artist, date, release_type, genres, rating info",
"total": "integer count of items returned on this page"
}
}About the Rate Your Music API
Release and Artist Data
get_release_details accepts a release URL path and returns structured metadata: title, artist, average_rating, rating_count, primary_genres, secondary_genres, descriptors, and a tracklist array where each track carries num, name, duration, and has_lyrics. get_artist_details takes an artist URL and returns the artist's associated genre tags alongside a discography array that includes each release's title, url, year, rating, and ratings_count. For song-level data, get_song_details provides its own independent primary_genres and secondary_genres classification separate from the album it appears on.
Charts and Genre Taxonomy
get_charts returns 40 items per page and supports filtering via media_type, chart_type, and year (point-in-time years like 2024, ranges like 2020-2024, or all-time). Each chart entry includes rank, release_name, artist, date, release_type, genres, and rating information. get_genres lists the full genre catalog as name/URL pairs, and get_genre_details returns a genre's name, description, and parents array, letting you traverse the genre hierarchy upward from any node.
Search
The search endpoint accepts a query string and an optional search_type filter to scope results to artists, releases, or genres. Each result object returns a name, url, and type field. URLs returned by search can be passed directly into get_release_details, get_artist_details, or get_genre_details to fetch full records.
The Rate Your Music API is a managed, monitored endpoint for rateyourmusic.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when rateyourmusic.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 rateyourmusic.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?+
- Build a music discovery tool that surfaces top-rated albums by genre using
get_chartsfiltered bychart_typeandyear. - Populate a music database with tracklists, descriptors, and genre tags by calling
get_release_detailsfor each release URL. - Map the RYM genre hierarchy by traversing
get_genresand resolving parent relationships viaget_genre_details. - Aggregate an artist's full discography with ratings and years using
get_artist_details. - Compare decade-by-decade chart rankings by querying
get_chartswith year ranges like2000-2009and2010-2019. - Identify genre drift on a song versus its parent album by comparing
primary_genresfromget_song_detailsagainstget_release_details. - Build an autocomplete search backed by the
searchendpoint scoped to releases or artists viasearch_type.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Rate Your Music have an official developer API?+
What does `get_charts` return, and how granular is the filtering?+
get_charts returns paginated arrays of 40 chart entries per page. Each entry includes rank, release_name, artist, date, release_type, genres, and rating fields. You can filter by media_type (e.g. album vs. track), chart_type, and year — which accepts a single year like 2024, a range like 2010-2019, or the string all-time. Filters can be combined.Does the API expose user reviews or lists beyond aggregate ratings?+
average_rating, rating_count, descriptors, and genre tags. Individual user reviews, user-created lists, and personal shelving data are not covered. You can fork this API on Parse and revise it to add endpoints targeting those page sections.What is the difference between `primary_genres` and `secondary_genres` on a release?+
get_release_details returns both arrays separately, reflecting RYM's own distinction between a release's main genre classification and its supplementary genre tags. The combined genres field merges both arrays into a flat list if you don't need the distinction. get_song_details applies the same split independently at the song level.Does the API cover release metadata like record labels, country of origin, or catalog numbers?+
get_release_details covers title, artist, genres, tracklist, descriptors, and rating data. Fields like record label, country, catalog number, and release format details are not returned. You can fork this API on Parse and revise it to add those fields.