Rate Your Music APIrateyourmusic.com ↗
Access RYM album ratings, artist discographies, music charts, genre hierarchies, and user reviews via 8 structured JSON endpoints.
What is the Rate Your Music API?
The Rate Your Music API exposes 8 endpoints covering album and song metadata, artist discographies, genre hierarchies, user-written reviews, and ranked charts from rateyourmusic.com. get_charts returns up to 40 ranked entries per page filterable by year, media type, and geographic location. get_release_details delivers full tracklists, descriptor tags, and split primary/secondary genre arrays. get_release_reviews paginates public user reviews eight at a time with per-reviewer ratings and permalinks.
curl -X GET 'https://api.parse.bot/scraper/4543201b-0c81-4415-b1a4-83478db54412/get_charts?page=1&year=all-time&location=chile&chart_type=top&media_type=album' \ -H 'X-API-Key: $PARSE_API_KEY'
Returns one page (40 entries) of a Rate Your Music chart for albums, tracks, EPs or singles, ordered by chart rank. Each entry carries rank, release_name, release_url, artist, artist_url, date and derived year, release_type, primary_genres/secondary_genres plus the combined genres list, average_rating (also as rating), rating_count (also as ratings_count) and reviews_count. For media_type=track the site's song chart is served: release_name/release_url refer to the song page, release_type is an empty string and reviews_count is null because the site does not show them for songs. Optional geographic filtering restricts the chart to artists from one RYM location slug; when a location is supplied the response echoes it as top-level location and filters.location and reports the site's display name in filters.location_name. If the site does not recognise the location slug it serves the worldwide chart instead, and this endpoint returns a stale_input error (kind input_not_found) rather than that worldwide data. Paging is by the page input (1-indexed, defaults to the first page, omission returns page 1); rank continues across pages (page 2 starts at 41). One request per call. A page past the end returns an empty items array.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination (1-indexed). |
| year | string | Year or year range (e.g. 2024, 2020-2024, all-time). |
| location | string | RYM chart location slug restricting the chart to artists from that place: lowercase words joined by hyphens (e.g. chile, united-states). Omit for the worldwide chart. An unrecognised slug yields a stale_input error instead of worldwide results. |
| chart_type | string | Type of chart. |
| media_type | string | Type of media. track selects the site's song chart. |
{
"type": "object",
"fields": {
"page": "integer, the page that was fetched",
"items": "array of chart entries: rank (integer, continues across pages), release_name, release_url (release page, or song page for media_type=track), artist, artist_url, date (site date string), year (4-digit string derived from date, null if absent), release_type (empty string for track charts), primary_genres, secondary_genres, genres (primary + secondary combined), average_rating and rating (same string value), rating_count and ratings_count (same abbreviated string value, e.g. 4k), reviews_count (null for track charts)",
"total": "integer count of items returned on this page",
"filters": "object echoing the applied chart_type, media_type, year, location (slug or null) and location_name (site display name of the location, e.g. Chile; null when no location)",
"location": "string location slug that was applied, or null for the worldwide chart"
}
}About the Rate Your Music API
Album and Release Data
get_release_details accepts a release URL path (e.g. /release/album/kendrick-lamar/to-pimp-a-butterfly/) and returns the title, artist, average rating, rating count, descriptor strings, and a full tracklist where each track carries its number, name, duration, and a has_lyrics flag. Genres are split into primary_genres, secondary_genres, and a separate movements array — useful when you need to distinguish stylistic movements from the main genre classification RYM uses.
Charts and Filtering
get_charts pages through RYM album, EP, track, and singles charts. The year parameter accepts a single year (2024), a range (2020-2024), or all-time. The location parameter takes a lowercase hyphen-joined slug to restrict results to artists from a specific place. Each returned entry includes rank (continuing across pages), release_name, release_url, artist, artist_url, date, year, release_type, and combined plus split genre arrays. The filters object in the response echoes back every applied parameter including the resolved location_name.
Artist and Genre Endpoints
get_artist_details returns an artist's name, associated genre list, origin as a comma-separated place string (Formed location for bands, Born location for solo artists), the extracted country field, and a discography array with title, URL, year, rating, and ratings count per release. For genre data, get_genres lists every genre on the site with name and URL, and get_genre_details returns a genre's name, parent genre names, and the site's description text — enough to reconstruct the genre hierarchy.
Reviews and Search
get_release_reviews paginates public reviews for any release URL at 8 reviews per page. Each review object includes review_id, reviewer, reviewer_url, permalink, date, rating, and the review text. The has_more boolean and total_pages integer make it straightforward to walk all pages. search accepts a free-text query and an optional search_type filter, returning name, URL, and type (artist, release, genre, or other) for each match.
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 app that surfaces top-rated albums by genre and decade using
get_chartswith year-range and genre filters. - Populate a music database with tracklists, ratings, and descriptor tags by calling
get_release_detailsfor each release URL. - Map artist origins to geographic coordinates by combining
get_artist_detailsoriginandcountryfields with a geocoding service. - Analyze genre relationships and build a genre graph by combining
get_genresandget_genre_detailsparent arrays. - Aggregate user sentiment for a release by collecting review text and ratings from
get_release_reviewsacross all pages. - Track chart movement over time by periodically fetching
get_chartsand storing rank changes per release. - Resolve search queries to canonical RYM artist or release URLs using
searchbefore fetching detailed metadata.
| 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?+
How does `get_charts` handle location filtering, and what does the response include?+
get_charts accepts a location parameter as a lowercase hyphen-joined slug (e.g. united-states). When applied, the chart is restricted to artists from that location. The response includes a filters object that echoes the applied chart_type, media_type, year, and location slug, plus a resolved location_name showing how the site displays that location. If no location is applied, location and location_name are null and the chart is worldwide.What is the difference between `genres`, `primary_genres`, `secondary_genres`, and `movements` in `get_release_details`?+
genres is the combined array of primary and secondary genre strings. primary_genres and secondary_genres reflect RYM's own distinction between the main genre tags and supporting/descriptive genre tags for a release. movements is a separate array drawn from the Movements section on the release page, which RYM treats as distinct from its genre classification.Are user lists, collection data, or individual user profiles accessible through this API?+
How does pagination work for `get_release_reviews`, and are reviews sorted?+
get_release_reviews returns up to 8 reviews per page in the order the site serves them to anonymous visitors. The sort_label field is always null because no sort control is exposed for unauthenticated views. Use has_more to check whether additional pages exist and total_pages to know the last available page number.