Albumoftheyear APIalbumoftheyear.org ↗
Access album metadata, critic and user scores, genres, labels, release dates, and ranked lists from albumoftheyear.org via 7 structured endpoints.
What is the Albumoftheyear API?
The Album of the Year API exposes 7 endpoints covering album search, full metadata, ranked best-album lists, new releases, upcoming releases, genres, and tags from albumoftheyear.org. The get_album_details endpoint returns critic scores, user scores, cover art URLs, genre arrays, label arrays, release dates, and critic review rows for any album — all in a single request.
curl -X GET 'https://api.parse.bot/scraper/d9c42eb6-5bec-496f-a97d-2e8b9cc8521d/search_albums?page=1&query=Radiohead' \ -H 'X-API-Key: $PARSE_API_KEY'
Full-text search over albums. query matches artist names and album titles. Returns paginated results ordered by relevance. Each result carries a path suitable for get_album_details.
| 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 echoed back",
"results": "array of album summary 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 API
Search and Album Metadata
The search_albums endpoint accepts a query string matched against artist names and album titles, returning paginated result objects that each carry artist, album_title, year, type, and a path field. That path feeds directly into get_album_details, which returns the full metadata record: critic_score, user_score, cover_url (or null when no cover is available), genres (array of strings), labels (array of strings), release_date, and a critic_review_rows array containing individual critic reviews listed on the page. Extra detail fields include producer, writer, tags, and format.
Ranked Lists and Release Feeds
get_best_albums lets you pull ranked album lists filtered by year (a four-digit string or 'all') and list_type, ordered by critic score, review count, or user score. Each result includes rank, critic_score, user_score, genres, and a path for further detail lookup. get_new_releases returns a reverse-chronological release feed with a period parameter supporting 'all' or 'this_week'; each release object includes critic_score, user_score, review counts, and a has_more boolean for pagination. get_upcoming_releases mirrors this shape for scheduled future releases, with the info field carrying the release date and format string exactly as the site displays it (e.g., 'Sep 11 • LP').
Genres and Tags
get_genres returns the complete genre index in one response — no pagination — with each genre object carrying name, numeric_id, and url. The numeric_id matches the identifiers used in site URLs, making it suitable for constructing filtered queries. get_tags returns the site's "Popular Album Tags" cloud (around 50 tags) with name, slug, featured (boolean), and url per tag, plus a total count. This is the full tag surface the site publishes publicly; there is no exhaustive tag index beyond this cloud.
The Albumoftheyear API is a managed, monitored endpoint for albumoftheyear.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when albumoftheyear.org 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 albumoftheyear.org 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 feed by polling
get_new_releaseswithperiod='this_week'to surface freshly reviewed albums. - Populate a database of critic consensus scores by combining
get_best_albumsyear filters withget_album_detailsfor full metadata. - Track upcoming album release dates and formats using
get_upcoming_releasesand itsinfofield. - Map genre distribution across highly rated albums by joining
get_best_albumsresults with thegenresarray fromget_album_details. - Autocomplete album or artist search in a music app using the
search_albumsendpoint's paginated relevance-ranked results. - Enumerate all recognized genre identifiers for a filtering UI using
get_genres, which returnsnumeric_idvalues aligned with site URL conventions. - Analyze label output and critical reception by aggregating
labelsandcritic_scorefields fromget_album_detailsacross a catalog.
| 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 albumoftheyear.org offer an official developer API?+
What does `get_album_details` return beyond basic scores?+
get_album_details returns critic_score, user_score, cover_url (null when the page has no cover), genres (array), labels (array), release_date, and a critic_review_rows array of individual critic review entries. It also surfaces extra detail fields including producer, writer, tags, and format — all in a single request using the album_path parameter.Can I filter `get_best_albums` results by genre?+
get_best_albums endpoint supports filtering by year and list_type (critic score, user score, or review count) but does not currently accept a genre filter parameter. The genres field is present on each returned album object. You can fork this API on Parse and revise it to add genre-based filtering against the numeric IDs returned by get_genres.Are individual user reviews or review text available?+
get_album_details returns critic_review_rows (critic reviews) and aggregate user_score and review counts, but not per-user review content. You can fork this API on Parse and revise it to add a user-reviews endpoint if that data is needed.How complete is the tags endpoint, and can I fetch all albums under a specific tag?+
get_tags endpoint returns the ~50 tags in the site's public "Popular Album Tags" cloud, with name, slug, featured, and url per tag. Fetching a filtered list of albums by tag slug is not currently covered. You can fork this API on Parse and revise it to add a tag-browsing endpoint using the slug values returned.