albumoftheyear.org APIalbumoftheyear.org ↗
Access album search, critic/user scores, genres, labels, and new releases from albumoftheyear.org via 4 structured endpoints.
curl -X GET 'https://api.parse.bot/scraper/d9c42eb6-5bec-496f-a97d-2e8b9cc8521d/search_albums?page=1&query=Kendrick+Lamar' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for albums by query string. Returns paginated results matching the search term, including artist name, album title, year, type, and URL path.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination. |
| queryrequired | string | Search query for album or artist name. |
{
"type": "object",
"fields": {
"page": "current page number",
"query": "the search query string that was used",
"results": "array of album objects with artist, album_title, year, type, path, and full_url"
},
"sample": {
"data": {
"page": 1,
"query": "Kendrick Lamar",
"results": [
{
"path": "/album/29250-kendrick-lamar-to-pimp-a-butterfly.php",
"type": "LP",
"year": "2015",
"artist": "Kendrick Lamar",
"full_url": "https://www.albumoftheyear.org/album/29250-kendrick-lamar-to-pimp-a-butterfly.php",
"album_title": "To Pimp a Butterfly"
}
]
},
"status": "success"
}
}About the albumoftheyear.org API
The Album of the Year API exposes 4 endpoints that cover album search, detailed metadata, ranked lists, and new releases from albumoftheyear.org. The get_album_details endpoint returns critic scores, user scores, genres, record labels, release date, and extra details like producer and tags for any album identified by its path. The get_best_albums endpoint supports filtering by year and list type, making it straightforward to pull ranked album data programmatically.
Endpoints and Data Coverage
The search_albums endpoint accepts a query string and an optional page integer, returning an array of results where each object includes artist, album_title, year, type, path, and full_url. The path field is what you pass to get_album_details to retrieve deeper metadata. Pagination is supported across all list-returning endpoints via the page parameter.
Album Metadata
get_album_details takes an album_path (e.g. /album/29250-kendrick-lamar-to-pimp-a-butterfly) and returns critic_score, user_score, genres (array), labels (array), release_date, and an extra_details object that may contain key-value pairs for Format, Producer, Writer, and Tags. Scores are returned as strings or null when not yet available.
Ranked Lists and New Releases
get_best_albums accepts an optional year string (e.g. '2024' or 'all') and a list_type parameter with accepted values of '6-highest-rated', '7-most-reviewed', or 'user-highest-rated'. Each album object in the response includes rank, critic_score, user_score, release_date, genres, and both path and full_url for chaining into get_album_details. The get_new_releases endpoint returns a paginated feed of recent albums with artist, album_title, info, path, and full_url.
- Build a music discovery app that surfaces critic-rated and user-rated albums by year using
get_best_albums. - Track newly released albums in near real-time by polling
get_new_releasesand filtering by artist or genre. - Aggregate genre and label distribution across top-ranked albums by combining
get_best_albumswithget_album_details. - Populate a music database with structured metadata — producer, writer, format, and tags — via
extra_detailsfromget_album_details. - Power an album recommendation engine that uses critic and user scores alongside genre arrays to match listener preferences.
- Monitor a specific artist's catalog by searching with
search_albumsand iterating paths throughget_album_details.
| 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 | 250 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 albumoftheyear.org have an official developer API?+
What does `get_best_albums` return and how can I filter it?+
rank, artist, album_title, critic_score, user_score, release_date, genres, path, and full_url. You filter by passing a year string (e.g. '2024' or 'all') and a list_type value of '6-highest-rated', '7-most-reviewed', or 'user-highest-rated'. Omitting those parameters returns the default ranked list.Are individual track listings or streaming links available through this API?+
How complete are critic and user scores in `get_album_details`?+
critic_score and user_score are returned as strings when present, or null when the album has not yet accumulated enough ratings on albumoftheyear.org. Newly released albums retrieved via get_new_releases are especially likely to return null scores.